E3De::OpenLidar

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

Certain operations, for example, E3DLidar::GetPointsInPolygon and E3De::GenerateProducts require that LiDAR files are built into an optimized file format (similar to building a pyramid for a raster image). If necessary, this is done automatically when OpenLidar is called and may take some time. See the AUXILIARY_URI keyword for setting the location where the auxiliary files (including the optimized file and an .ini project file) will be created.

If the DIRECT_READ keyword is used and a single LiDAR file (.las, .ntf, .sid, .txt, or .bin) is specified by URI, it can be read directly without building an optimized file using E3DLidar::GetPointsInRange. Its projection information, if available, can be read directly using the SPATIALREF property. However, it is not possible to call E3DLidar::GetPointsInCircle, E3DLidar::GetPointsInPolygon, E3DLidar::GetPointsInRect, E3DLidar::GetPointsInTile, or E3De::GenerateProducts if the DIRECT_READ keyword is set.

OpenLidar cannot be called twice to open two datasets simultaneously. The first dataset must be closed with E3DLidar::Close before calling OpenLidar on the second, or the CLOSE_PREVIOUS keyword must be set. The exception is when using DIRECT_READ; in that case, OpenLidar can be called multiple times without calling E3DLidar::Close between calls.

If ENVI LiDAR is not in headless mode (the user interface is displayed) and DIRECT_READ is not set then the LiDAR data will also be opened in the user interface.

This method has been deprecated. Use ENVI::OpenPointCloud or ENVI::QueryPointCloud instead.

Example

; Create a headless instance

e = E3De(/HEADLESS)

; Open a las file

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

  SUBDIRECTORY = ['DataSample'])

lidar = e.OpenLidar(file, /DIRECT_READ)

; Print number of points and extents

print, lidar.Total_Number_Of_Points

print, lidar.Data_Range

; Close any open lidar objects

e.Close

Syntax

Result = E3De.OpenLidar(URI [, AUXILIARY_URI=string] [, CALLBACK=value] [, /CLOSE_PREVIOUS] [, /DIRECT_READ] [, ERROR=variable] [, /REBUILD_AUXILIARY_FILES] [, SPATIALREF=E3DLidarspatialref] [, TXT_FORMAT=value] [, TEXT_SKIP_HEADER_LINES]=value)

Return Value

This method returns a reference to an E3DLidar object.

Arguments

URI

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

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

Keywords

AUXILIARY_URI

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

The input LiDAR files saved to an optimized file format.
A project file (.ini) that can be passed to OpenLidar to re-open the optimized version of the all the LiDAR 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 AUXILIARY_URI keyword is not set or is set to !NULL, then the auxiliary files directory will be created in the same location and with the same filename (without the file extension) as the first LiDAR file passed to OpenLidar.

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

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

CALLBACK

Building the auxiliary files (optimized file format, etc.) can be time consuming. Set this keyword to a user-defined callback object to receive progress updates. This object must include ::OnProgress and ::OnDone methods. While OpenLidar is processing ::OnProgress will be called periodically with a progress value as a percentage. The ::OnDone method is called when OpenLidar is complete. An example callback object is shown below:

function GenerateProductsCallback::Init

  return, 1

end

pro GenerateProductsCallback::OnDone

  print, "done"

end

pro GenerateProductsCallback::OnProgress, progress

  self.progress = progress

  print, progress

end

pro GenerateProductsCallback__define

  void = {GenerateProductsCallback, $

    progress: 0 $

end

CLOSE_PREVIOUS

Two LiDAR datasets cannot be open simultaneously unless the DIRECT_READ keyword is set. If the DIRECT_READ keyword is not used, set this keyword to automatically close the open dataset instead of having to call E3DLidar::Close.

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

DIRECT_READ

Read directly from the single LiDAR file (.las, .ntf, .sid, .txt, or .bin) specified by URI without creating an optimized copy of the data. If this keyword is set, the following methods cannot be called: E3DLidar::GetPointsInCircle, E3DLidar::GetPointsInPolygon, E3DLidar::GetPointsInRect, E3DLidar::GetPointsInTile, E3De::GenerateProducts.

Building the optimized file can be time consuming and involves reprojecting the data to UTM WGS84. By setting the DIRECT_READ keyword, the original, unmodified data can be read from the LiDAR file using E3DLidar::GetPointsInRange. The projection information can be read from the LiDAR file using the E3DLidar SPATIALREF property.

An error will be thrown if DIRECT_READ is specified and a project (.ini) or an array of LiDAR files are passed by URI.

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.

REBUILD_AUXILIARY_FILES

Set this keyword to force the auxiliary files (described previously) to be rebuilt if they already exist while opening one or more .las, .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 E3DLidarSpatialRef object that specifies the coordinate system used by the LiDAR 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 LiDAR 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 LiDAR file does contain coordinate system information and this keyword is specified, the coordinate system specified will override that in the LiDAR file.

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

Note: If DIRECT_READ is not set, then the points will be reprojected from the coordinate system specified by SPATIALREF to UTM WGS84. The SPATIALREF property on the returned E3DLidar will reflect this change.

TXT_FORMAT

Use this keyword to specify the columns for text format point datasets. This is a 1-D array of strings where 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 LiDAR 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.