VDEMINGEST

Description

Parameters

vdemingest(points, contours, breaklin, struct3d, elevopts, elevrang, ridges, valleys, cliffs, filv, mapunits, elevunit, elevconv)

Parameter descriptions

POINTS

The name or names of the input files, folders, or both that contain elevation points.

Elevation points are individual x and y points with an associated elevation. The points from all input files are collected and written to a POINTS vector segment.

You can use the string to specify a single file, a recursive folder search, or a more sophisticated match by using an asterisk (*) as a wildcard. For examples of using a wildcard, see Specifying input files and folders.

CONTOURS

The name or names of the input files, folders, or both that contain contours.

Contours are three-dimensional lines that have a single elevation for the entire line (break lines, in contrast, have a different elevation at each vertex). The contours from all input files are collected and written to a CONTOURS vector segment.

BREAKLIN

The name or names of the input files, folders, or both that contain break lines.

Break lines are three-dimensional lines in which each vertex can have a different elevation. The break lines from all input files are collected and written to a BREAKLIN vector segment.

STRUCT3D

The name or names of the input files, folders, or both that contain three-dimensional structures.

These are typically man-made structures, such as bridges or buildings, represented by three-dimensional polygons. The polygons from all input files are collected and written to a STRUCT3D vector segment. Break lines representing features, such as roof ridges, can also be included.

ELEVOPTS

The names of attribute fields that contain elevation data or special-processing flags.

If point or contour data has the elevation value specified as a numeric attribute, you specify the name of the field here. You can specify multiple names, separated by blank spaces or commas. If you provide multiple names, the first name matching a field will be used.

You can also use the string to specify which return to use in a LIDAR-point (.las / .laz) file. The value RETURN1 specifies the first return, RETURNALL specifies all returns, and RETURNLAST specifies the last return. Do not use RETURN1, RETURNALL, and RETURNLAST at the same time. By default, RETURN1 is selected.

With LIDAR-point files, RETURN1, RETURNALL, or RETURNLAST can also include an optional suffix to indicate which classifications to process. For example, RETURN1:"Ground,Road Surface" only processes "Ground" and "Road Surface" points. Class-name matching is case-insensitive. Use a comma to separate class names. Surround the class names with double quotes if supplying more than one class or if there are spaces in the class name. Partial class names will process those points that have the partial class name as a substring of the point's class. For example, RETURNALL:"ro" processes only points that have "ro" anywhere in the class name.

If you specify the option NONAME, each vector segment will be named NONAME rather than POINTS, CONTOURS, and so on. This is sometimes useful in complex situations (for more information on complex situations, see NONAME.

With POINT data, each point is considered as a separate shape. By specifying PACKPOINTS, 10,000 points are packed into each shape. This reduces the size on disk by half and allows VDEMINGEST to run faster. However, the points are in a nonstandard representation; therefore, if you intend to use the points to run an algorithm other than VDEMINT, do not specify PACKPOINTS.

Typically, with STRUCT3D, data lines, points and polygons are ingested. However, if you want only true polygons, you can use the POLYGONONLY option to discard lines and points. A true polygon is a single line in which the start and end point are the same. Therefore, ensure that you have true polygons, and not a number of separate line structures that appear to be a true polygons; these will be eliminated.

This parameter is optional.

ELEVRANG

The range of elevation values accepted for points, contours, and break lines.

When you specify a single value, it is considered to be a maximum.

Points, contours, or break lines containing values outside the range are not ingested. If any vertex of a break line is outside the range, the entire break line is ignored.

This parameter is optional.

RIDGES

The names of the input files, folders, or both that contain ridges.

Ridges are two-dimensional lines that have no associated elevation, but represent lines where elevation falls off on either side. The ridges from all input files are collected and written to a RIDGES vector segment.

VALLEYS

The input files, folders, or both that contain valleys.

Valleys are two-dimensional lines that have no associated elevation, but represent lines where elevation rises on either side. The valleys from all input files are collected and written to a VALLEYS vector segment.

CLIFFS

The input files, folders, or both that contain cliffs.

Cliffs are two-dimensional lines that have no associated elevation, but represent discontinuities where elevations on either side are interpolated independently of surrounding information. The cliffs from all input files are collected and written to a CLIFFS vector segment.

FILV

The name of the PCIDSK file to which to write the generated vector segments. This file is created automatically, and a file with the same name must not already exist in the folder.

MAPUNITS

The output projection of the ingested vectors. All input will be reprojected automatically to that of the output.

If no value is specified for this parameter, the output projection will use the projection of the first input vector segment found, by default.

This parameter is optional.

ELEVUNIT

The units of the elevation values.

FEET are defined as 0.3048 meters (corresponding to International Feet); US_FEET are defined as 1,200/3,937 meters (corresponding to U.S. Survey Feet).

ELEVCONV

Converts the elevation values provided with the vector information to the units specified for Output elevation units (ELEVUNIT), such as feet to meters.

If no value is specified for this parameter (typical usage), the elevation values supplied with the vector data are assumed to already be in compatible units and no conversion is applied.

You specify two numbers as the value of this parameter: the first defines the offset, and the second defines the scale.

The conversion formula is as follows:

                    scale × (vector_elevation_value + offset) = elevation_value
                    

Details

At times, projects do not have raster digital elevation models (DEM); instead, they have hundreds—perhaps thousands—of small files that contain points and vector representations of contours, break lines, and features, such as ridges, valleys, and cliffs.

By using VDEMINGEST, you can merge all of the information in these point and vector files into a single PCIDSK (.pix) file, which you can then use as input to VDEMSETUP and VDEMINT to create a high-quality raster DEM.

Specifying input files and folders

You specify the locations of the input files with the POINTS, CONTOURS, BREAKLINES, STRUCT3D, RIDGES, VALLEYS, and CLIFFS parameters.

It is recommended that you specify the full path to the folder, (for example, "d:\\lines"); otherwise, VDEMINGEST uses the current working folder, which may not be readily apparent.

You can specify up to 32 exclusions by using -xxx separated by commas; for example: "-abc, -ignore, -x". You cannot use the asterisk (*) wildcard in an exclusion. When any portion of the name of a file or folder matches the exclusion definition, it is excluded.

Input vector and point files

Point and vector data representing elevation varies greatly in file formats, how it is organized on disk, and internal representations. While VDEMINGEST can interpret many varieties of data, organizational structure, and so on, in some cases you may need to reorganize files into folders, reformat data using third-party utilities, or both before using VDEMINGEST.

Supported formats of the input files are as described in the following table.

Output results

The vertices in each vector segment created are three-dimensional and have do not have attribute fields. Any attribute fields in the original input file are not copied. The VALLEYS, RIDGES, and CLIFFS segments are also three-dimensional by default, and may contain elevations, but VDEMINT ignores any elevation information in such segments.

Vector segments greater than 1 GB in size are divided into multiple segments, each with the same name, to limit memory consumption.

VDEMINT uses the POINTS, CONTOURS, BREAKLIN, STRUCT3D, VALLEYS, RIDGES, and CLIFFS segments to interpolate a raster digital elevation model (DEM). VDEMINT can use the OUTLINE segment to constrain the interpolated DEM to prevent it from bleeding into the background.

The EXTENTS segment contains a polygon outline and information, such as the file name, for each file ingested. Although VDEMINT does not use this segment, it can be useful for QA. For example, if you open the raster DEM generated by VDEMINT in CATALYST Professional Focus, you can open this segment as a vector overlay. If the DEM contains anomalies, you can identify and open the input vector file associated with the data in that area in the Attribute Manager window.

The SUMMARY segment contains a copy of the text report. This is useful if the original report was not generated or was lost. The report can be written to a separate text file by using TEXWRIT, or viewed in Focus.

The output file has extents bounding all of the input data. The file and each vector segment will have the same projection. Although no raster data channel is created with the file, the image x and y dimensions of the file are set automatically; therefore, if a raster data channel is added to the file (using CRCHN32R, for example), it will have square pixels and approximately 4 million data points. You can then use VDEMINT with the data file as both input and output to provide a 'preview' of the DEM that you can keep with the vector data.

Examples

                                 d:/data
                                    |
+----------------------+------------------------+-----------------+
\points          \breaklines                  \lines             \other
=======                |                        |               ======
sheet1.pix      +------------+           +-------------+        contour_1.shp      
sheet5.txt    \area5       \map1       \sheet1      \sheet5     contour_5.pix
sheet5.gav    ======       =====       =======      =======     contour_top.shp
              breaks.pix   bline.shp   cliff.shp    cliff.shp   bridges.shp
                                       valley.shp   valley.shp

from pci.vdemingest import vdemingest

points   = r"d:\data\points\*.*"            # all files in \points folder
contours = r"d:\data\other\con*.*,-top"     # contours, exclude file contour_top
breaklin = r"d:\data\breaklines"            # all files in all subfolders
struct3d = r"d:\data\bridges.shp"           # some 3-D bridges
elevopts = ""                               # no special options
elevrang = []                               # accept all elevations
ridges   = r"d:\data\other\contour_top.shp" # file contour_top is a ridge
valleys  = r"d:\data\lines\**\val*.shp"     # valley files and in subfolders
cliffs   = r"d:\data\lines\**\val*.shp"     # cliff files and in subfolders
filv     = "vector.pix"                     # output vector file
mapunits = ""                               # default, projection from first file
elevunit = "METER"
elevconv = []
vdemingest( points, contours, breaklin, struct3d, elevopts, elevrang, ridges, valleys, cliffs, filv, mapunits, elevunit, elevconv )

You have LIDAR data in a .las file with four returns. By default, VDEMINGEST uses only the last return.

You want to use both the first and last returns instead. You do this by running VDEMINGEST three separate times: the first to get the first return, the second to get the last return, and the third to merge the two resulting .pix files into a single .pix file. Because the LIDAR data has 100M+ points, use the PACKPOINTS option to reduce the size of the resulting .pix file by half and double the run time.

from pci.vdemingest import vdemingest

points    =    "POINTS"
breaklin    =    "BREAKLINES"
ridges    =    ""
valleys    =    ""
cliffs    =    ""
contours    =    ""
filv    =    "vector.pix"
mapunits    =    "UTM 11 D0"

vdemingest( points, contours, breaklin, struct3d, elevopts, elevrang, ridges, valleys, cliffs, filv, mapunits, elevunit, elevconv )

You have a contour file, mixedlines.shp, in which the elevation value is in the attribute field ZVAL. Unfortunately, this file also contains valleys identified using the elevation -99,999. These must be separated from the contour data; otherwise, the resulting DEM will be generated incorrectly. You separate them by running VDEMINGEST three separate times: the first to get the true contours, the second to get the valleys, and the third to merge the two resulting .pix files into a single .pix file.

A special consideration here is to use the NONAME option in the second run. Without this option, the extracted contour lines (representing valleys) are stored in a segment named CONTOURS, which is always assumed to be contours by VDEMINGEST. However, by using the NONAME option, the vector segment will be called NONAME and VDEMINGEST will bypass the default assumptions.

from pci.vdemingest import vdemingest

points      = ""
contours    = "mixedlines.shp"
breaklin    = ""
elevopts    = "ZVAL"
elevrang   = [-10000,10000]      # a safe range for real data
ridges      = ""
valleys     = ""
cliffs      = ""
filv        = "realcontours.pix"
mapunits    = "UTM 11 D0"       # UTM projection

vdemingest( points, contours, breaklin, struct3d, elevopts, elevrang, ridges, valleys, cliffs, filv, mapunits, elevunit, elevconv )

elevopts    = "ZVAL, NONAME"
elevrang   = [-99999,-99999]
filv        = "realvalleys.pix"

vdemingest( points, breaklin, ridges, valleys, cliffs, contours, filv, mapunits )

points      = ""
contours    = "realcontours.pix"
breaklin    = ""
elevopts    = ""                # ZVAL not needed since .pix vectors are x, y, and z
elevrang   = []                  # accept everything
ridges      = ""
valleys     = "realvalleys.pix"
cliffs      = ""
filv        = "final.pix"
mapunits    = ""               # will default to UTM from first input file

vdemingest( points, contours, breaklin, struct3d, elevopts, elevrang, ridges, valleys, cliffs, filv, mapunits, elevunit, elevconv )