ENVI::OpenPointCloud

The OpenPointCloud function method opens one or more LAS files (.las, .laz, or .ntf); MrSID files (.sid); text files (.txt); or Terrasolid files (.bin). It also opens a single project file (.ini).

Operations such as ENVIPointCloud::GetPointsInPolygon require that point cloud files are built into an optimized file format, which spatially orders the points. Optimization is done automatically when OpenPointCloud is called. See the PROJECT_URI keyword for setting the location where the auxiliary files (including the optimized file and an .ini project file) will be created. Data optimization with OpenPointCloud can be time consuming and it involves reprojecting the data to UTM WGS84. To skip data optimization, you can use ENVI::QueryPointCloud. With QueryPointCloud you can read unmodified data from the point cloud file.

OpenPointCloud cannot be called twice to open two datasets simultaneously. The first dataset must be closed with ENVIPointCloud::Close before calling OpenPointCloud on the second dataset, or set the CLOSE_PREVIOUS keyword.

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))

 

; Print information about the point cloud.

print, pointcloud

 

; Close the point cloud object.

pointcloud.Close

Syntax

Result = ENVI.OpenPointCloud(URI [, Keywords=value])

Return Value

This method returns a reference to an ENVIPointCloud object.

Arguments

URI

A scalar string that is a fully-qualified path to either a project file (.ini), or to a single point cloud file (.las, .laz, .txt, .ntf, .sid, or .bin).

or

An array of strings containing the fully-qualified paths to multiple point cloud files (.las, .laz, .txt, .ntf, .sid, or .bin).

Keywords

CLOSE_PREVIOUS

Two point cloud datasets cannot be open simultaneously. Set this keyword to automatically close the open dataset instead of calling ENVIPointCloud::Close.

Note: Any ENVIPointCloud object references to the previously open data become invalid and should not be used.

ERROR

Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''). If an error occurs and the routine is a function, then the function result will be undefined.

When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.

See Manage Errors for more information on error handling in ENVI programming.

PROJECT_URI

A scalar string specifying the fully qualified path to a folder that contains, or will contain, the project files. These include:

If the folder does not exist, it will be created. An error will be thrown if it is a read-only location.

If the PROJECT_URI keyword is not set or is set to !NULL, then the project files directory will be created in the same location and with the same filename (without the file extension) as the first point cloud file passed to OpenPointCloud.

If the folder already exists and contains files they will be used rather than generating new ones. It is therefore important that the correct existing folder is selected for the point cloud data being opened.

The PROJECT_URI does not need to be specified when opening an existing .ini file.

REBUILD_PROJECT

Set this keyword to force the project files (described previously) to be rebuilt if they already exist while opening one or more .las, .laz, .ntf, .sid,.txt, or .bin files. This includes the generated products, for example, buildings shapefile, DEM, etc. This keyword is ignored when opening an .ini file.

SPATIALREF

An ENVIPointCloudSpatialRef object that specifies the coordinate system used by the point cloud files being opened. This does not need to be specified if opening .las files that already contain coordinate system information (for example, in the LAS header) or if opening an .ini file.

If this keyword is not set, the first point cloud file in the URI array is checked for coordinate system information. All the files are assumed to use the same coordinate system.

If the first file does not contain coordinate system information and this keyword is not specified, then the coordinates will be treated as arbitrary (undefined geographic location) with units in meters.

If the first point cloud file does contain coordinate system information and this keyword is specified, the coordinate system specified will override that in the point cloud file.

An error will be thrown if this keyword is specified when opening an .ini file.

TXT_FORMAT

Use this keyword to specify the columns for text format point datasets. This is a 1-D array of strings were each entry in the array details the column type. The supported strings are: x, y, height, intensity, red, green, blue, ignore.

format = ['x', 'y', 'height', 'intensity', 'red', 'green', 'blue']

This keyword is ignored if the input point cloud files are not in .txt format.

TXT_SKIP_HEADER_LINES

Use this keyword to specify how many lines to skip from the beginning of the text file to get to the first point. Some text files have information at the beginning that describe what is in the file. Use TXT_SKIP_HEADER_LINES to skip over those lines to get to the first point. If this is not set correctly, it will not be possible to read from the text file. The default value is 0.

This keyword is ignored if the input point cloud files are not in .txt format.

Progress Reporting

OpenPointCloud pre-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)

fileName ='datasample.las'

 

; create subscriber

OpenPointCloudSubscriber = OBJ_NEW('OpenPointCloudSubscriber', fileName)

Channel = e.GetBroadcastChannel()

 

; attach subscriber to ENVIBroadCastChannel

Channel.Subscribe, OpenPointCloudSubscriber

 

pointcloud = e.OpenPointCloud(fileName)

 

e.close

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

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

; Class Name:

; OpenPointCloudSubscriber

;

; Purpose:

; Object to monitor pre-processing progress

;

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

; openPointCloudSubscriber::Init

;

function openPointCloudSubscriber::Init, srcFileName

compile_opt idl2, hidden

 

self.srcFileName = srcFileName

 

return, 1

end

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

; PointCloudTaskSubscriber::Cleanup

;

pro pointCloudTaskSubscriber::Cleanup

compile_opt idl2, hidden

 

print, "clean"

 

end

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

; openPointCloudSubscriber::OnMessage

;

pro openPointCloudSubscriber::OnMessage, msg

compile_opt idl2

 

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

 

oSrc = msg.source

uri = oSrc.uri

 

if self.srcFileName eq uri then begin

 

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

if isa(msg, "envifinishmessage") then print, "Pre-processing complete."

if isa(msg, "envistartmessage") then print, "Pre-processing started."

 

endif

 

endif

 

end

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

; Object Definition

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

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

; openPointCloudSubscriber__define

;

pro openPointCloudSubscriber__define

compile_opt idl2, hidden

 

void = {openPointCloudSubscriber, $

inherits enviMessageHandler, $

srcFileName : '' $

}

end

Version History

ENVI 5.3

Introduced

API Version

4.2

See Also

ENVI, ENVIPointCloud, ENVIPointCloud::GetPointsInCircle, ENVIPointCloud::GetPointsInPolygon, ENVIPointCloud::GetPointsInRange, ENVIPointCloud::GetPointsInRect, ENVIPointCloud::GetPointsInTile, ENVIPointCloudSpatialRef, ENVI::QueryPointCloud