| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Examples :: Algorithm :: Related |
| Back to top |
| Back to top |
grdpin(filv, file, tfile, vecunit, dbvs, dboc, numsmp, fldnme)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILV | str | Input vector file name | 0 - | |
| FILE* | str | Output file name | 1 - | |
| TFILE | str | Text file name | 0 - | |
| VECUNIT | str | Vector units | 0 - 16 | PIXEL | UTM | others |
| DBVS | List[int] | Input vector segment | 0 - 1 | |
| DBOC* | List[int] | Output raster channel | 1 - 1 | |
| NUMSMP | List[int] | Number of sample points | 0 - 1 | 1 - 12 Default: 6 |
| FLDNME | str | Field name for elevation | 0 - 64 | Default: ATTRIBUTE |
| Back to top |
FILV
Specifies the name of the file that contains the vector segments to be rasterized. If this parameter is not specified, it will be assumed to be the same as FILE.
FILE
Specifies the name of the PCIDSK file to receive the output interpolated image.
TFILE
Specifies the name of the text file that contains data points which serve as basis for the interpolation. The text file may contain up to 50,000 data points.
The data points to be read in should be in xyz coordinates. For example:
503800 5014386 125 503737 5014434 120 505391 5013333 190...
VECUNIT
Specifies the units in which the point coordinates in TFILE are stored. This defines the range and accuracy for coordinates and ensures that vector segments with different units cannot be merged.
If DBVS is specified, VECUNIT is not required and is ignored. If VECUNIT is not specified and is required, the georeference units from segment 1 are used.
For example: -15.5005 longitude can be specified as 15d30'1.8"W
VECUNIT can specify the UTM grid zone number and row, and Earth model, as follows:
UTM mm r Ennn
Ennn: specifies the Earth model, where the model number is between 0 and 19. If the Earth model is not specified, it is assumed to be E000 (Clarke 1866). The Earth model can be specified for LONG/LAT (and other units except PIXEL), as follows:
LONG/LAT Ennn
For more information on how to specify VECUNIT and a list of supported Earth models, see "Projections and Earth Models" in the Technical Reference section of the Online Help.
PIXEL coordinates have a range of (+ or -) 2097151 and a resolution rounded to the thousandth.
UTM and METRE coordinates handle 0 to 10,000,000 meters N (or E) and have a resolution rounded to the nearest cm.
LONG/LAT coordinates have a range of (+ or -) 180 degrees and a resolution rounded to 2.5 cm at the equator.
DBVS
Specifies the vector segment in which the attribute values of the point structures will be used as the basis for the interpolation. Confidences for all attribute values are assumed to be 1.0.
The vector segment can specify up to 50,000 point structures. If this parameter is not specified, TFILE must be specified. If both TFILE and DBVS are specified, an error message is issued and the function stops execution.
DBOC
Specifies the output image channel to receive the interpolated result.
NUMSMP
Specifies the number of closest points to consider when interpolating a point. More data points generate a smoother result but a loss of local detail, while fewer data points provide less interpolation.
If this parameter is set to 1, the output image is a proximal map (Thiessen polygons), where each output pixel is the value of the nearest known (input) data point (that is, no interpolation).
The value of this parameter must be less than or equal to the total number of points specified by TFILE or in DBVS.
FLDNME
Specifies the field name that contains the elevation values.
If this parameter is specified as ZCOORD, the actual z-coordinates of the vectors are used. Field names are not case-sensitive, and they do not need to be specified in complete form. If more than one match exists, the first name is used.
The Field Name (FLDNME) parameter is required only for vector layers that contain 3-D points or contours. For 3-D lines, the z-coordinates are automatically used. For 2-D layers, the elevation values are not specified.
The same name applies to all contour and 3-D point segments specified in the input vectors (DBVS) parameter. The segments that do not satisfy this requirement can be converted to the required format using ZVALTRNS.
If a field name other than ZCOORD is specified but is not found, VDEMINT attempts to use the z-coordinates of each vertex or point; this may, however, lead to unexpected results.
| Back to top |
GRDPIN is used to read gray-level values for up to 50,000 pixel locations in order to generate a raster image based on interpolation between the specified gray levels. Optionally associated with each input pixel gray level is a user-specified confidence level.
The gray-level data values are read from either a text file (TFILE) or from the point attributes of a vector segment (DBVS) stored in the image file (FILE). If both or neither of TFILE and DBVS are specified, GRDPIN stops execution with an error message.
If TFILE is the choice of data input, the VECUNIT parameter must be specified. The coordinate data will be interpreted according to the specified vector units. It is especially important that you select a value for VECUNIT that accurately reflects the type and accuracy of the coordinates being read. For input from DBVS, however, the data type can be determined from the segment header, and VECUNIT is ignored.
Up to 200 characters per text record may be used for text files. Fields within a text file can have up to 16 characters each and are separated by one or more spaces.
The TFILE file must have the following format:
X-Coord Y-Coord Value [Confidence]
...
...
Fields must be separated by one or more blanks, NOT by commas.
If VECUNIT="LONG/LAT", longitude and latitude can be entered either as real numbers, or as degrees, minutes, seconds and hemisphere with NO BLANKS OR COMMAS between the d ' and " symbols.
If TFILE is specified, VECUNIT must be specified. If TFILE is not specified, DBVS must be specified. If both TFILE and DBVS are specified, an error message is issued and GRDPIN stops execution.
You can control the results of the interpolation with the NUMSMP (Number of Sample Points) parameter. This value defines the number of closest points taken into account during the interpolation procedure. A larger NUMSMP value yields a smoother output image at the expense of local detail. If NUMSMP is equal to 1, a proximal map will be generated in which each output pixel takes on the value of its nearest known (input) data point. In other words, interpolation is not performed. NUMSMP is restricted to the range of 1 through 12 and, if not specified, defaults to 6.
Each vector may contain more than one attribute field. The FLDNME (Field Name) parameter is used to select the attribute field to use.
If the input data is being read from a text file, the accuracy of the results can be improved by associating with each input value a level of confidence in that estimate. Confidence levels may range from 0.0 to 1.0 and, if not specified, default to 1.0. Vector segments do not enable user entry of confidence levels. For this reason, when input is read from a vector segment, all points have an assumed confidence of 1.0 (or 100%).
| Back to top |
The following example will use the RAS2PNT task to generate a vector segment containing point data from channel 6 of the file irvine.pix.
The points of this vector segment will serve as input to create (1) an interpolated image channel, and (2) a proximal map (where each output pixel receives the value of the closest point attribute).
from pci.ras2pnt import * file = "irvine.pix" dbic = [6] dbsd = 'Example' filo = "irvine.pix" ftype = "" foptions= "" lasc = [] ras2pnt ( file, dbic, filo, dbsd, ftype, foptions )
Run VECREP to determine which attribute field to use.
from pci.vecrep import * file = "irvine.pix" dbvs = [lasc] # use last created vector segment from RAS2PNT vrtype = 'VERT' vecrep ( file, dbvs, vrtype )
VECREP Vector Segment Report Contents: Example Layer Type: POINTS Length: 25.0 Kbytes Structures: 181 V 6.0 Georeference Units: UTM 11 S E000 Projection : Universal Transverse Mercator Datum - Ellipsoid : NAD 27 - Clarke 1866 Grid units : METER Bounds:( 428795.000E, 3719055.000N), ( 444065.000E, 3734355.000N) Field Type Width Precision Justify =----- ---- ----- --------- ------- Attribute Integer 8 n/a Right Group Integer 8 n/a Right
After looking at the available attribute fields (attribute and group), we decide that we wish to choose "attribute". Because attribute is the default, FLDNME does not need to be specified.
Create an interpolated output channel using GRDPIN.
from pci.grdpin import * filv = "irvine.pix" file = "irvine.pix" tfile = '' # input not from text file vecunit = '' # use units of DBVS dbvs = [lasc] # use last created vector segment from RAS2PNT dboc = [8] fldnme = '' # default, ATTRIBUTE numsmp = [2] # use 2 closest points grdpin ( filv, file, tfile, vecunit, dbvs, dboc, numsmp, fldnme )
Run NUM to display a portion of the interpolated result.
from pci.num import * file = "irvine.pix" dbic = [8] dbiw = [229,0,15,15] # print window num ( file, dbic, dbiw )
NUM Database Image Numeric Window
irvine.pix [S 11PIC 512P 512L]
8 [ 8U] GRDPIN from segment 33, NUMSMP= 2
Offset: ( 229, 0) Size: ( 15, 15)
2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
3 3 3 3 3 3 3 3 3 3 4 4 4 4 4
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4
+-----------------------------------------------------------
1| 24 25 25 26 26 27 27 27 28 28 28 31 31 31 31
2| 25 25 26 26 26 27 27 28 28 28 29 31 31 31 31
3| 25 25 26 26 27 27 27 28 28 29 29 31 31 31 31
4| 25 25 26 26 27 27 28 28 28 29 29 31 31 31 31
5| 25 26 26 27 27 28 28 28 29 29 29 31 31 31 31
6| 25 26 26 27 27 28 28 29 29 29 29 31 31 31 31
7| 26 26 27 27 28 28 28 29 29 29 30 31 31 31 31
8| 26 26 27 27 28 28 29 29 29 30 30 31 31 31 31
9| 26 26 27 27 28 28 29 29 29 30 31 31 31 31 31
10| 26 27 27 28 28 29 29 29 30 30 31 31 31 31 31
11| 26 27 27 28 28 29 29 29 30 30 31 31 31 31 31
12| 27 27 28 28 28 29 29 30 30 30 32 32 32 31 31
13| 27 27 28 28 29 29 29 30 30 30 32 32 31 31 31
14| 27 27 28 28 29 29 29 30 30 32 32 32 31 31 31
15| 27 28 28 28 29 29 29 30 30 32 32 32 31 31 31
Create a proximal map output channel using GRDPIN.
from pci.grdpin import * filv = "irvine.pix" file = "irvine.pix" tfile = '' # input not from text file vecunit = '' # use units of DBVS dbvs = [lasc] # use last created vector segment from RAS2PNT dboc = [9] fldnme = '' # default, ATTRIBUTE numsmp = [1] # use closest point (proximal map) grdpin ( filv, file, tfile, vecunit, dbvs, dboc, numsmp, fldnme )
Run NUM to display a portion of the proximal map result.
from pci.num import * file = "irvine.pix" dbic = [9] dbiw = [229,0,15,15] # print window num ( file, dbic, dbiw )
NUM Database Numeric Window
irvine.pix [S 11PIC 512P 512L]
9 [ 8U] GRDPIN from segment 33, NUMSMP= 1
Offset: ( 229, 0) Size: ( 15, 15)
2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
3 3 3 3 3 3 3 3 3 3 4 4 4 4 4
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4
+-----------------------------------------------------------
1| 21 21 21 21 31 31 31 31 31 31 31 31 31 31 31
2| 21 21 21 21 31 31 31 31 31 31 31 31 31 31 31
3| 21 21 21 31 31 31 31 31 31 31 31 31 31 31 31
4| 21 21 21 31 31 31 31 31 31 31 31 31 31 31 31
5| 21 21 31 31 31 31 31 31 31 31 31 31 31 31 31
6| 21 21 31 31 31 31 31 31 31 31 31 31 31 31 31
7| 21 31 31 31 31 31 31 31 31 31 31 31 31 31 31
8| 21 31 31 31 31 31 31 31 31 31 31 31 31 31 31
9| 21 31 31 31 31 31 31 31 31 31 31 31 31 31 31
10| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
11| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
12| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
13| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
14| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
15| 31 31 31 31 31 31 31 31 31 31 31 31 31 31 31
| Back to top |
Among the many grid interpolation algorithms that exist, the most widely used models for use with discrete points are local methods using k-nearest neighbors; that is, the k nearest of all sample points to the grid point in question) weighted by their distances from the grid point.
(i) Interpolation Algorithm
We expect for most phenomena that the gray-level value at any grid point should be most like the sample points nearest to the grid point. Thus, the influence a neighboring sample point has on the estimated value is weighted by the inverse distance to the grid point. The interpolation equation then becomes:
k
__ Zi
\ ------
/_ (Di**2) / Ci
i=1
Zxy = ---------------------------
k
__ 1
\ ------
/_ (Di**2) / Ci
i=1
where, for each k-nearest neighbor, Zi is its gray level, Di is its distance from the current grid point being interpolated, Ci is its confidence level, and Zxy is the interpolated result for the current grid point.
(ii) k-nearest Point Search Algorithm
For each grid point, the k-nearest neighbors must be identified from the entire data set before the distance-weighted equation can be employed. The search for the k-neighbors is the most computationally intensive part of the interpolation process. Intuitively, one has only to calculate the distance to each attribute and select the closest ones. Although simple in design, this is a very time-consuming process.
Improving upon this basic approach, we have adopted the search strategy described by Michael E. Hodgson in "The Professional Geographer" 41(1) 1989. This algorithm "learns", from its previous search, the distance within which the k-nearest neighboring points of the current grid point can be found.
An initial preprocessing phase partitions the image file into a matrix of n X n subregions or cells. An array is created which associates each sample point with a particular matrix cell. The k-nearest neighbors of the first grid point are determined by a brute force search of all sample points.
© PCI Geomatics Enterprises, Inc.®, 2024. All rights reserved.