PointCloudFeatureExtraction Task

This task performs feature extraction on point cloud data. Building, tree, and power line feature extraction requires an ENVI Feature Extraction license to generate. Contact your sales representative for more information.

To process a spatial subset instead of the entire dataset, use ENVISpatialSubsetPointCloud before calling the ENVITask, as shown in the example code.

An ENVIPointCloud object has a complete set of parameters saved on disk in the ENVIPointCloud PROJECT_URI location. Any parameters that have not been set on the ENVITask (that is, are !NULL) will have values read from the saved parameters and used for processing when Execute is called.

To inspect the saved parameters before calling Execute, call the Validate method. This will load the saved parameter values into the ENVITask (apart from those parameters that have already been set).

Example

; Start the application

e = ENVI(/HEADLESS)

 

; Open a las file

file = FILEPATH('DataSample.las', ROOT_DIR=e.ROOT_DIR, $

SUBDIRECTORY = ['data','lidar'])

pointcloud = e.OpenPointCloud(file, $

  PROJECT_URI=Filepath('DataSample', /TMP))

 

; Process a 300m x 300m subrect

subset = ENVISpatialSubsetPointCloud(pointcloud, [593847.0, 5289683.0, 594147.00, 5289983.0])

 

; Get the point cloud feature extraction task from the catalog of ENVI tasks

task = ENVITask('PointCloudFeatureExtraction')

 

; Define inputs

Task.INPUT_POINT_CLOUD = Subset

 

; Make sure that DEM, building and trees generation is enabled

Task.DEM_GENERATE = 1

Task.BUILDINGS_GENERATE = 1

Task.TREES_GENERATE = 1

 

; Run the task

Result = task.Validate(VALIDATION_EXCEPTION=msg)

print, 'Executing Point Cloud Feature Extraction Task'

Task.Execute

 

; Get the output product filenames

productsInfo = Task.OUTPUT_PRODUCTS_INFO

print, 'DEM Filename: ', productsInfo.DEM_URI

print, 'Buildings Filename: ', productsInfo.BUILDINGS_URI

print, 'Trees Filename: ', productsInfo.TREES_URI

 

; Close any open point cloud objects

pointcloud.Close

Syntax

Result = ENVITask('PointCloudFeatureExtraction')

Arguments

None

Methods

This task inherits the following methods from ENVITask:

AddParameter

Execute

Parameter

ParameterNames

RemoveParameter

Properties

Properties marked as (Get) can be retrieved, but not set.

All properties are optional.

Input/Output Properties

This task inherits the following properties from ENVITask:

COMMUTE_ON_DOWNSAMPLE

COMMUTE_ON_SUBSET

DESCRIPTION

DISPLAY_NAME

NAME

REVISION

TAGS

This task also contains the following properties:

INPUT_POINT_CLOUD

Specify an ENVIPointCloud object on which to perform the feature extraction. The input cannot be an ENVIQueryPointCloud object.

SAVE_PARAMETERS

If set to 1, all the parameters in the ENVITask should be saved in the INPUT_POINT_CLOUD's PROJECT_URI location. The next time the data is opened and set in INPUT_POINT_CLOUD, calling ENVITask::Validate or ENVITask::Execute will restore these saved parameters (without overwriting any parameters set on the ENVITask). The default is 0, do not save the parameters.

OUTPUT_PRODUCTS_INFO (Get)

A reference to an ENVIPointCloudProductsInfo object that contains paths to all the generated files.

Building Extraction Properties

BUILDINGS_BOX_MODELS_TYPE

An integer to set the roof contour height. Use when the BUILDINGS_USE_BOX_MODELS value is 1. Set as follows:

BUILDINGS_URI

A string value specifying the filename for the buildings product.

BUILDINGS_FORMAT

A string value specifying the format of the buildings product output. Valid values are:

BUILDINGS_GENERATE

A boolean value to generate buildings products as follows. If DEM_GENERATE is enabled, you can improve the accuracy of the DEM by also enabling BUILDINGS_GENERATE, as this will automatically flatten the DEM directly underneath the buildings.

BUILDINGS_MINIMUM_AREA

A float value specifying the minimum area for building planes. The buildings algorithm searches for all flat surfaces, then measures the area of each flat surface. Surfaces with an area less than this value are filtered out before processing continues. Units: square meters. Default: 10.

BUILDINGS_NEAR_GROUND_FILTER_WIDTH

A float value specifying the near-ground filter width. This is useful for preventing buses, trucks, train cars, and so forth from being classified as buildings. Near-ground filtering occurs after BUILDINGS_MINIMUM_AREA filtering. Objects less than 5 meters above the ground that have a width less than this value are filtered out of the building classification. Units: centimeters. Default: 300.

BUILDINGS_PLANE_SURFACE_TOLERANCE

A float value specifying the plane surface tolerance. This is the allowed vertical tolerance for searching for the surface in the neighboring points. This setting is useful for databases that have higher noise, and also when the nature of surfaces requires a higher tolerance, such as curved surfaces. If trees are present, increasing this value also increases the likelihood of falsely identifying trees as buildings. Range: greater than or equal to 15.0 and less than or equal to 60.0. Units: centimeters. Default: 30.

BUILDINGS_POINTS_IN_RANGE

A float value specifying the buildings points range. This is useful for detecting building planes when the point density is not equal throughout the data. Typically, this value should be 0 (Auto in the user interface); however, if the data density is low (1 point per m2 or lower), large buildings such as hangars or warehouses may not be classified as buildings. Increasing this value to 1.2 or 1.4 will help detect them, but also increases the likelihood of falsely identifying trees as buildings. Range: greater than or equal to 0.5 and less than or equal to 1.4. Units: meters. Default: 0.

BUILDINGS_USE_BOX_MODELS

A boolean value as follows:

DEM/TIN Extraction

DEM_CONSTANT_HEIGHT_OFFSET

A float value to specify an offset for the DEM grid in a noisy dataset. The elevation of the DEM may be slightly offset in noisy datasets due to inaccurate points above and below the ground. If this occurs, you can shift the terrain grid up or down. A positive number will move the DEM up, and a negative number will move the DEM down. Units: Centimeters. Default: 2.

DEM_CONTOURS_URI

A string value specifying the filename for the DEM contours product.

DEM_CONTOURS_FORMAT

A string specifying the format of the DEM contours product output. Valid values are:

DEM_CONTOURS_GENERATE

A boolean value to generate DEM contours as follows:

DEM_CONTOURS_LINES_SPACING

A float value specifying the vertical spacing between the DEM height contour lines. This step is done after the DEM grid is generated; therefore, it does not affect the DEM grid generation. Range: greater than or equal to 50 and less than or equal to 1000. Units: centimeters. Default: 200.

DEM_URI

A string value specifying the filename for the DEM product.

DEM_FILTER_DATABASE_EDGES

A boolean value. In some terrain, such as forested areas with trees at the edge of the dataset, the algorithms of the DEM grid generation do not detect the edges of the database well. Set the value as follows:

DEM_FILTER_LOWER_POINTS

An unsigned char value. This parameter is useful for filtering points that are lower than the terrain. Valid values are:

DEM_FORMAT

A string value specifying the format of the DEM product output. Valid values are:

DEM_GENERATE

A boolean value to generate DEM-related products as follows. If DEM_GENERATE is enabled, you can improve the accuracy of the DEM by also enabling BUILDINGS_GENERATE, as this will automatically flatten the DEM directly underneath the buildings.

DEM_GRID_RESOLUTION

An unsigned long integer value specifying the grid resolution to use when creating the DEM. Internally, a 50 or 100 centimeter grid resolution is used and sub-sampled to 200-1000 centimeters, if selected. The 50 centimeter grid tunes the DEM extraction algorithms to be more sensitive at some points, and requires higher density data. If the project density is lower than 4 points / m2, selecting a 50 centimeter grid will not result in better resolution of the DEM, and the amount of time to create the DEM will increase. To save processing time, 100 centimeter resolution is recommended unless a very detailed 50 centimeter posting DEM is needed. Range: greater than or equal to 50, and less than or equal to 1000. Units: centimeters. Default: 100.

DEM_NEAR_TERRAIN_CLASSIFICATION

A float value to specify the near-terrain classification. Classifying points as near-terrain is useful to catch low objects that are not part of the terrain and are also not buildings, trees or power lines. For example, low vegetation, cars, buses, and so forth could all be classified as near-terrain objects. This classification is done after the DEM grid is created. When set to 50, a point is classified as terrain if it is within 50 centimeters of the grid. You can set near-terrain classification between 15 and 50 centimeters. For example, if this value is set at 20, points with a distance of 0 to 20 centimeters from the grid are classified as terrain points, and points with a distance of 20 to 50 centimeters are classified as near-terrain points. Range: greater than or equal to 15 and less than or equal to 50. Units: centimeters. Default: 50.

DEM_SENSITIVITY

A float value. Use when the DEM_VARIABLE_SENSITIVITY_ALGORITHM value is 1. The higher the sensitivity, the better it works with higher-frequency terrain, but increases the likelihood of falsely identifying terrain as buildings. Default: 30 (medium sensitivity).

DEM_TIN_GENERATE

A boolean value to generate a TIN-related product as follows:

DEM_TIN_URI

A string value specifying the filename for the DEM TIN product.

DEM_TIN_FORMAT

A string value specifying the format of the DEM TIN product output. Valid values are:

DEM_TIN_MAX_ERROR

A float value specifying the maximum permitted vertical distance between a triangle and the actual terrain. The distance between the TIN and the actual terrain introduces errors into the TIN mesh. Reducing the this value results in a more accurate TIN, but increases triangle count.

This value and the DEM_TIN_MAX_POLYGON_DENSITY value will affect the TIN representation of the ground. TIN production does not affect the DEM grid production algorithm. TIN production uses only the points classified as terrain. Reducing the value of DEM_NEAR_TERRAIN_CLASSIFICATION results in reducing the number of points that are classified as terrain, thereby reducing both the time for TIN generation and the size of the TIN generated. Units: centimeters. Default: 10.

DEM_TIN_MAX_POLYGON_DENSITY

A float value specifying the maximum number of triangles that will be produced in a 100x100 meter area when producing the TIN. This value and the DEM_TIN_MAX_ERROR parameter will affect the TIN representation of the ground. If this value is set too low, it may not be possible to achieve the DEM_TIN_MAX_ERROR. Default: 10000.

DEM_VARIABLE_SENSITIVITY_ALGORITHM

A boolean value to use the variable sensitivity algorithm as follows:

DSM Extraction

DSM_URI

A string value specifying the filename for the DSM product.

DSM_FORMAT

A string value specifying the format of the DSM product output. Valid values are:

DSM_GENERATE

A boolean value to generate a DSM-related product as follows:

DSM_GRID_RESOLUTION

An unsigned long integer specifying the resolution of the DSM grid. Range: Greater than or equal to 5 and less than or equal to 1000. Setting the resolution to lower than 25 will slow processing time. Units: centimeters. Default: 100.

When you generate a high-resolution DSM (that is, use a setting lower than 25 cm), you may need to increase the GENERAL_MAX_POINTS_DENSITY setting to get the best results from your data. Note that setting the resolution to lower than 25 cm will increase processing time.

DSM_USE_POWERLINES_POINTS

A boolean value to specify whether power lines and cables will be part of the DSM. If Viewshed Analysis will be used with the processed project, power lines and cables need to be included in the DSM. Valid values are:

Filtered Point Cloud Generation

FILTERED_POINTCLOUD_GENERATE

A boolean value to generate point cloud-related products as follows:

FILTERED_POINTCLOUD_URI

A string value specifying the base filename for the filtered point cloud product. This name can have the following formats:

<base_filename>_unclassified_000.las

 

<base_filename>_<product>_000.las (ex. pc_trees_000.las)

FILTERED_POINTCLOUD_FORMAT

A string specifying the format of the filtered point cloud product output. Valid values are:

FILTERED_POINTCLOUD_SEPARATE_BY_CLASS

A boolean value to separate point cloud datasets, each containing data from an individual class, as follows:

FILTERED_POINTCLOUD_SIZE_LIMIT

A float value. Set this to limit the size of each of the generated point cloud files. If the value specified is less than 10000 (10MB), then a value of 10000 will be used. Units: kilobytes. Default: 500000.

General Product

GENERAL_CLIP_MAX_HEIGHT

A float value specifying the maximum height extent of the source project at which to filter high-altitude noise. Set the value to the highest known point in the area. All points above this height are ignored. The default is the height value of the highest point in the file.

GENERAL_CLIP_MIN_HEIGHT

A float value specifying the minimum height extent of the source project at which to filter false low points. Set the value to the lowest known point in the area. All points below this height are ignored. The default is the actual lowest point in the file.

GENERAL_MAX_POINTS_DENSITY

A float value that limits the number of processed and viewed points. The limit is applied by taking only some of the points per block of data (a single block is 32x32 meters). Limiting the density shortens the processing time of the building and power line detection algorithms, but might also limit the number of extracted features. Used mostly with terrestrial and mobile scanning databases, as the density is much higher closer to the scanner. Specify the units using GENERAL_POINTS_DENSITY_UNITS. Default: 50 points per square meter, regardless of the density of the input; or 0.141421 Ground Sample Distance, in meters.

GENERAL_POINTS_DENSITY_UNITS

An integer specifying the units of the maximum points density. Use with GENERAL_MAX_POINTS_DENSITY. Valid values are:

SPATIALREF

An ENVIPointCloudSpatialRef object that specifies the desired coordinate system of the generated products.

NUMBER_OF_CORES

An unsigned long integer specifying the number of cores to use for product processing when multiple CPUs are available.

Zero indicates to use all available cores for processing. If a value less than the maximum cores is specified, the remainder will be available for other processes. If a value greater than the number of available cores is specified, then the maximum number of available cores will be used. Default: 0.

Orthophoto Extraction

ORTHOPHOTO_URI

A string value specifying the filename for the orthophoto product.

ORTHOPHOTO_FORMAT

A string specifying the format of the orthophoto product output. Valid values are:

ORTHOPHOTO_GENERATE

A boolean value to generate orthophoto-related products as follows:

ORTHOPHOTO_INTENSITY_RANGE_MAX

A float value. All points with intensity higher than this value appear white. This setting also affects the intensity display in the Main window. Use the default value unless you see that the file is all or mostly black, in which case decrease the value. You can invert the ORTHOPHOTO_INTENSITY_RANGE_MAX and ORTHOPHOTO_INTENSITY_RANGE_MIN intensity range values so that darker features will appear darker. Default: 255.

ORTHOPHOTO_INTENSITY_RANGE_MIN

A float value. All points with intensity lower than this value appear black. This setting also affects the intensity display in the Main window. Use the default value unless you see that the file is all or mostly white, in which case increase the value. You can invert the ORTHOPHOTO_INTENSITY_RANGE_MIN and ORTHOPHOTO_INTENSITY_RANGE_MAX intensity range values so that darker features will appear lighter. Default: 0.

ORTHOPHOTO_RESOLUTION

An unsigned long integer specifying the resolution of the generated orthophoto. The orthophoto is based on LiDAR intensity or RGB (if supported by the point data format; otherwise, it is grayscale intensity). Range: greater than or equal to 25 and less than or equal to 800. Units: centimeters per pixel. Default: 100.

Power Line and Power Pole Extraction

POWERLINES_URI

A string value specifying the filename for the power lines product.

POWERLINES_FILTER_BY_MIN_JOINED_LENGTH

A boolean value as follows:

Power lines are generated by extracting individual power line segments, then joining appropriate segments together. The minimum joined length refers to the entire length of the power line composed of multiple power line segments. If many false positive power lines are extracted, then set POWERLINES_FILTER_BY_MIN_JOINED_LENGTH to 1 and enter a suitable value for POWERLINES_MIN_JOINED_LENGTH to filter out false positives.

POWERLINES_FILTER_TREES_BELOW_POWERLINES

A boolean value as follows:

Sometimes trees considerably lower than power lines may be incorrectly extended up to the power lines. This filter attempts to vertically separate tree and power line points, but sometimes incorrectly removes the entire tree even when the tree is adjacent to power lines rather than directly below them.

If the results of tree extraction are noticeably worse when extracting trees and power lines compared to extracting only trees (such as large gaps of unclassified points), then set POWERLINES_FILTER_TREES_BELOW_POWERLINES to 0 to disable filtering trees below power lines.

POWERLINES_FORMAT

A string value specifying the format of the power lines product output. Valid values are:

POWERLINES_GENERATE

A boolean value to generate power lines and power poles products as follows:

POWERLINES_MIN_HEIGHT

The minimum height from the ground at which to detect power line points. Units: meters. Default: 6.

POWERLINES_MIN_JOINED_LENGTH

A float value. Specify the minimum length, in meters, that a span of joined power line segments must be to be classified. Detected joined power lines shorter than this value will not be classified as power lines. The default value is 20 meters, and the minimum value is 1 meter.

Note: Setting this value very high may result in filtering out many genuine power lines.

POWERLINES_MIN_LENGTH

A float value. Specify the minimum length, in meters, that a power line segment must be to be classified. Detected power line segments shorter than this value will not be classified as power lines. The default value is 10 meters, and the minimum value is 1 meter.

Note: Setting this value very low may result in the detection of many false positives.

POWERLINES_SEARCH_LOWKV

A boolean value as follows:

POWERLINES_SEARCH_WIDE

A boolean value as follows:

POWERPOLES_CLASS_EXTEND_TOP

A float value. See POWERPOLES_CLASS_RADIUS_LOW and POWERPOLES_MAX_RADIUS_TOP. The classification of the top part of the power pole is done by the width of the power poles arms. If a wider radius is needed, use this parameter to extend it. At the higher part of the power pole, points located this distance from the attachment points will be classified as power line points. Units: meters. Default: 0.

POWERPOLES_CLASS_RADIUS_LOW

A float value to specify the lower part of the pole from the ground level to the half of the pole height. This is used for classification after the power pole was identified. The classification is done in a cylinder around the pole center. If the radius of the power pole is known, set the parameter to the known radius of the base. For large pylons, if this parameter is not increased to a high enough value, not all of the points on the pylon will be classified as power pole. Units: meters. Default: 3.

POWERPOLES_DETECT

A boolean value as follows:

POWERPOLES_EXTEND_WIRES_DISTANCE

A float value to set the maximum power line gap to be corrected. This bridges gaps in the line from the end of the detected line to the next power pole. This algorithm assumes the power lines are not continuous for reasons such as:

Units: meters. Default: 40.

POWERPOLES_LOCATION_FILE (Set)

A string specifying the filename of the power pole locations file to import. The pole locations file is in ASCII CSV format, for example:

622967.510,5829323.700,109.355

622934.300,5829330.640,109.544

622908.220,5829337.950,109.628

622886.330,5829341.760,109.805

622856.430,5829348.280,110.018

622832.600,5829351.730,110.028

622775.250,5829360.800,109.760

622753.600,5829364.680,109.659

where:

Column 1: X location

Column 2: Y location

Column 3: Height (meters)

POWERPOLES_MAX_RADIUS_TOP

A float value indicating the maximum radius of the power pole arm. In most situations, there is no need to change it, as it is selected automatically by the attachment point spreading. Set this parameter so the algorithm will not join attachment points with the wrong placement of the power pole base. This will happen if there are two parallel lines with separated power poles. Units: meters. Default: 10.

POWERPOLES_SEARCH_ADDITIONAL

Power poles can be imported from a file using the POWERPOLES_LOCATION_FILE property. A boolean value as follows:

Products Location

PRODUCTS_LOCATION

A string value specifying the name of the output folder to which the associated product files will be written. This location is a subfolder of the main project folder. Default: Products.

Tree Extraction

TREES_URI

A string value specifying the filename for the trees product.

TREES_FORMAT

A string value that specifies the file format to write the tree output to .cvs or .shp. Valid values are:

TREES_GENERATE

A boolean value to generate trees products as follows:

TREES_MAX_HEIGHT

A float value specifying the expected maximum height of trees in the project. Higher points will not be classified as trees. This avoids items such as cranes being classified as trees. Units: centimeters. Default: 5000.

TREES_MIN_HEIGHT

A float value specifying the expected minimum height of trees in the project. Points with dispersal characteristic of trees will be classified as trees. Units: centimeters. Default: 130.

TREES_MAX_RADIUS

A float value specifying the expected maximum radius of trees in the project. Units: centimeters. Default: 600.

TREES_MIN_RADIUS

A float value specifying the expected minimum radius of trees in the project. This avoids items such as lampposts being classified as trees. Units: centimeters. Default: 200.

Progress Reporting

Feature extraction processing can take a while to complete. You can monitor the progress of the feature extraction process by subscribing to the ENVIBroadcastChannel. For example:

e = envi(/HEADLESS)

pointcloud = e.OpenPointCloud('DataSample.las')

 

; Create the ENVITask

task = enviTask('PointCloudFeatureExtraction')

 

task.INPUT_POINT_CLOUD = pointcloud

task.BUILDINGS_GENERATE = 1

task.BUILDINGS_FORMAT = 'shp'

 

task.SAVE_PARAMETERS = 1

 

; Call validate to load the rest of the params from the project

v = task.Validate()

 

;; create task subscriber

PointCloudTaskSubscriber = OBJ_NEW('PointCloudTaskSubscriber', task)

Channel = e.GetBroadcastChannel()

 

; attach subscriber to ENVIBroadCastChannel

Channel.Subscribe, PointCloudTaskSubscriber

 

task.Execute

 

e.close

The PointCloudTaskSubscriber object implementation is shown below. The object needs to implement the ::OnMessage method.

;----------------------------------------------------------------------------

; Class Name:

; PointCloudTaskSubscriber

;

; Purpose:

; Object to monitor feature extraction progress

;

;----------------------------------------------------------------------------

; pointCloudTaskSubscriber::Init

;

function PointCloudTaskSubscriber::Init, oSrc

compile_opt idl2, hidden

 

self.oSrc = oSrc

 

return, 1

end

;----------------------------------------------------------------------------

; PointCloudTaskSubscriber::Cleanup

;

pro pointCloudTaskSubscriber::Cleanup

compile_opt idl2, hidden

 

print, "clean"

 

end

;----------------------------------------------------------------------------

; pointCloudTaskSubscriber::OnMessage

;

pro pointCloudTaskSubscriber::OnMessage, msg

compile_opt idl2

 

if isa(msg.source, "envipointcloudfeatureextractiontask") then begin

 

if self.oSrc eq msg.source then begin

 

if isa(msg, "enviprogressmessage") then print, msg.percent

if isa(msg, "envifinishmessage") then print, "Task complete."

if isa(msg, "envistartmessage") then print, "Task started."

 

endif

 

endif

 

end

;----------------------------------------------------------------------------

; Object Definition

;----------------------------------------------------------------------------

;----------------------------------------------------------------------------

; pointCloudTaskSubscriber__define

;

pro pointCloudTaskSubscriber__define

compile_opt idl2, hidden

 

void = {pointCloudTaskSubscriber, $

inherits enviMessageHandler, $

oSrc : obj_new(), $

dummy: 0b $

}

end

Version History

ENVI 5.3

Introduced

ENVI 5.6

The VIEWER_DATABASE_GENERATE property is obsolete. The 3D Viewer is no longer included with ENVI LiDAR.

API Version

4.2

See Also

ENVITask, ENVIPointCloud, ENVIPointCloudProductsInfo, ENVISpatialSubsetPointCloud