Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  ENVI API  >  Point Clouds  >  ENVI::OpenPointCloud

ENVI::OpenPointCloud

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


; Create a headless instance
e = ENVI(/HEADLESS)
 
; Open a LAS file
file = FILEPATH('DataSample.las', ROOT_DIR=e.ROOT_DIR, $
  SUBDIRECTORY = ['data','lidar'])
pointcloud = e.OpenPointCloud(file)
 
; Print information about the point cloud.
print, pointcloud
 
; Close the point cloud object.
pointcloud.Close

Syntax


Result = ENVI.OpenPointCloud(URI [, /CLOSE_PREVIOUS] [, ERROR=variable] [, PROJECT_URI=string] [, /REBUILD_PROJECT] [, SPATIALREF=ENVIPointCloudSpatialRef] [, TXT_FORMAT=value] [, TXT_SKIP_HEADER_LINES=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:

  • The input point cloud files saved to an optimized file format.
  • A project file (.ini) that can be passed to OpenPointCloud to re-open the optimized version of the all the point cloud files later. The filename will be the same as the folder name, with .ini appended. This file can also be opened in the ENVI LiDAR application.
  • The output of ENVI LiDAR processing, for example, building shapefiles, DEM, etc.

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


3.2

See Also


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



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us