Title: Interface to FUSION
Version: 0.1
Description: Set of functions that enable you to use the FUSION commands (Program available in: http://forsys.sefs.uw.edu/fusion/fusionlatest.html).
License: GPL-3
LazyData: true
Depends: R(≥ 3.5.0)
Imports: dplyr, sjmisc
OS_type: windows
Encoding: UTF-8
RoxygenNote: 7.1.1
NeedsCompilation: no
Packaged: 2021-03-04 10:31:50 UTC; Alba Garcia
Author: Alba García Cimarras ORCID iD [aut, cre]
Maintainer: Alba García Cimarras <alba.gcimarras@gmail.com>
Repository: CRAN
Date/Publication: 2021-03-17 12:50:03 UTC

ASCII2DTM

Description

ASCII2DTM converts raster data stored in ESRI ASCII raster format into a PLANS format data file. Data in the input ASCII raster file can represent a surface or raster data. ASCII2DTM converts areas containing NODATA values into areas with negative elevation values in the output data file.

Usage

ASCII2DTM(
  fusion.path = "C:/FUSION/",
  surfacefile,
  xyunits,
  zunits,
  coordsys,
  zone,
  horizdatum,
  vertdatum,
  Gridfile,
  switches = NULL
)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

surfacefile

Character. Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

xyunits

Character. Units for LIDAR data XY:

  • M - for meters.

  • F - for feet.

zunits

Character. Units for LIDAR data elevations:

  • M - for meters.

  • F - for feet.

coordsys

Numeric. Coordinate system for the canopy model:

  • 0 - for unknown.

  • 1 - for UTM.

  • 2 - for state plane.

zone

Numeric. Coordinate system zone for the canopy model (0 for unknown).

horizdatum

Numeric. Horizontal datum for the canopy model.

  • 0 - for unknown.

  • 1 - for NAD27.

  • 2 -for NAD83.

vertdatum

Numeric. LIDAR data file name or template or name of a text file containing a list of file names (list file must have .txt extension).

  • 0 - for unknown.

  • 1 - for NGVD29.

  • 2 - for NAVD88.

  • 3 - for GRS80.

Gridfile

Character. Name of the ESRI ASCII raster file containing surface data.

switches

Character. NULL as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /multiplier:# - Multiply all data values in the input surface by the constant.

  • /offset:# - Add the constant to all data values in the input surface. The constant can be negative.

  • /nan - Create FUSION index files for the output file.

Details

ASCII2DTM recognizes both the (xllcorner, yllcorner) and (xllcenter, yllcenter) methods for specifying the location of the raster data. The PLANS DTM format used in FUSION always assumes that the data point (grid point) in the lower left corner is the model origin and adjusts the location of the raster data accordingly.
ASCII2DTM examines the ASCII raster file to determine whether the elevation values are integers or floating point numbers. It creates the PLANS DTM file using either integer or 4-byte floating point values for the elevations.
ASCII2DTM always assumes that the data stored in ASCII raster format is interpreted as a raster. That is, the value is representative of the entire grid cell. For data that represent a surface where the values are actually elevations at specific points, the origin of the DTM file is set to the center of the lower left cell in the grid.
If you receive surface data in ESRI’s GRID format it is possible to use GDAL (http://www.gdal.org/) to convert the GRID data into ASCII raster format. Refer to Appendix D: Building multi-processor workflows using AreaProcessor for more details.
If you are using DTM2ASCII to convert data from the PLANS DTM format into ASCII raster format, you should always use the /raster switch in DTM2ASCII to ensure that you can convert the data back to the PLANS DTM format using ASCII2DTM.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

surfacefile<-'Z:/dtmfile.dtm'
Gridfile<- 'Z:/gridfile.asc'
ASCII2DTM(surfacefile = surfacefile,xyunits = 'M',zunits = 'M',
          coordsys = 1,zone = 0, horizdatum = 0, vertdatum = 0,
                    Gridfile = Gridfile, switches = NULL)

DTM2ENVI

Description

DTM2ENVI converts data stored in the PLANS DTM format into ENVI standard format raster files. Such files can be imported into GIS software such as ENVI and ArcInfo.

Usage

DTM2ENVI(fusion.path = "C:/FUSION/", inputfile, outputfile, switches = NULL)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

inputfile

is a character.Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

outputfile

Character. Name for the converted file. If outputfile is omitted, the output file name will be constructed from the inputfile name and the extension .xyz. If the /csv switch is used, the extension will be .csv.

switches

False as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /south - Specifies that data are located in the southern hemisphere.

Details

The ENVI data file is created using the same numeric format as the PLANS DTM file. All PLANS DTM data types are supported. Geo-referencing information is included in the ENVI header file using the “map info” tag. Areas in the DTM grid that have no data will be “marked” with a value of -9999.0 in the ENVI format file and the appropriate value will be included in the “data ignore value” tag in the ENVI header file.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

inputfile<-'Z:/dtmfile.dtm'
outputfile<- 'Z:/outputfile.xyz'
DTM2ENVI(inputfile = inputfile,outputfile = outputfile, switches = NULL)

DTM2TIF

Description

DTM2TIF converts data stored in the PLANS DTM format into a TIFF image and creates a world file that provides coordinate system reference data for the image. Such images can be imported into GIS software or used in other analysis processes.

Usage

DTM2TIF(fusion.path = "C:/FUSION/", inputfile, outputfile, switches = NULL)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

inputfile

is a character.Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

outputfile

Character. Name for the converted file. If outputfile is omitted, the output file name will be constructed from the inputfile name and the extension .xyz. If the /csv switch is used, the extension will be .csv.

switches

False as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /mask - Produces a mask image showing the areas in the DTM with valid data values. In the mask image, a value of 0 indicates a cell with invalid data (NODATA value) and a value of 255 indicates a cell with a valid data value.

  • /csv - Output XYZ points in comma separated value format (CSV). If /csv is used with no outputfile, an extension of .csv will be used to form the output file name.

  • /noheader - Do not include the column headings in CSV output files. Ignored if /csv is not used

Details

DTM2TIF creates grayscale TIFF images that represent the data stored in a PLANS format DTM file. The range of values in the DTM file is scaled to correspond to gray values ranging from 1 to 255 in the TIFF image. The gray level value of 0 is reserved to indicate NODATA areas in the DTM file (values less than 0.0). DTM2TIF creates a world file to provide coordinates system information for the TIFF image. The world file is named using the same file name as the TIFF image but with the extension .tfw.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

inputfile<-'Z:/dtmfile.dtm'
outputfile<- 'Z:/outputfile.xyz'
DTM2TIF(inputfile = inputfile,outputfile = outputfile, switches = NULL)

DTM2XYZ

Description

DTM2XYZ converts data stored in the PLANS DTM format into ASCII text files containing XYZ points. Such files can be imported into GIS software as point data with the elevation as an attribute or used in other analysis processes.

Usage

DTM2XYZ(fusion.path = "C:/FUSION/", inputfile, outputfile, switches = NULL)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

inputfile

is a character.Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

outputfile

Character. Name for the converted file. If outputfile is omitted, the output file name will be constructed from the inputfile name and the extension .xyz. If the /csv switch is used, the extension will be .csv.

switches

False as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /void - Output points from DTM with NODATA value (default is to omit). NODATA value is -9999.0 for the elevation

  • /csv - Output XYZ points in comma separated value format (CSV). If /csv is used with no outputfile, an extension of .csv will be used to form the output file name.

  • /noheader - Do not include the column headings in CSV output files. Ignored if /csv is not used

Details

The XYZ point file consists of one record for each grid point. Each record contains the X, Y, and elevation for the DTM grid point. If creating an ASCII text file, the values are separated by spaces and if creating a CSV format file, by commas. For CSV files, the first line contains column labels unless the /noheader switch is specified. If four or more of the directional searches find a valid elevation, the hole is filled using the average of all the values.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

inputfile<-'Z:/dtmfile.dtm'
outputfile<- 'Z:/outputfile.xyz'
DTM2XYZ(inputfile = inputfile,outputfile = outputfile, switches = NULL)

DTMDescribe

Description

DTMDescribe reads header information for PLANS format DTM files and outputs the information to an ASCII text file compatible with most spreadsheet and database programs. DTMDescribe can provide information for a single file or multiple files. Such files can be imported into GIS software as point data with the elevation as an attribute or used in other analysis processes.

Usage

DTMDescribe(fusion.path = "C:/FUSION/", inputfile, outputfile, switches = NULL)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

inputfile

is a character.DTM file name, DTM file template, or name of a text file containing a list of file names (must have .txt extension).

outputfile

Character. Name for the output ASCII CSV file. If no extension is provided, an extension (.csv) will be added.

switches

False as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /stats - Compute descriptive statistics for the data values in the DTM.

Details

DTMDescribe produced output files in comma separated value (CSV) format and includes column labels in the first line of the file. The following header information from the DTM file is included in the CSV file: File name Descriptive name Origin (X, Y) Upper right (X, Y) Number of columns Number of rows Column spacing Row spacing Minimum data value Maximum data value Horizontal units Vertical units Variable type Coordinate system Coordinate zone Horizontal datum Vertical datum

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

inputfile<-'Z:/dtmfile.dtm'
outputfile<- 'Z:/outputfile.xyz'
DTMDescribe(inputfile = inputfile,outputfile = outputfile, switches = NULL)

DTMHeader

Description

DTMHeader is an interactive program. It is described in the Command Line Utility section because it provides a means to examine and modify PLANS DTM file header information. DTMHeader allows you to easily view and change the header information for a PLANS DTM file. To make it most convenient, associate the .dtm extension with DTMHeader so you can simply double-click a .dtm file to view the header. The values in the header that can be modified are: Planimetric units, Elevation units, Descriptive name, Coordinate system and zone, Horizontal datum, Vertical datum.

Usage

DTMHeader(fusion.path = "C:/FUSION/", filename)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

filename

is a character.Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

Details

The ENVI data file is created using the same numeric format as the PLANS DTM file. All PLANS DTM data types are supported. Geo-referencing information is included in the ENVI header file using the “map info” tag. Areas in the DTM grid that have no data will be “marked” with a value of -9999.0 in the ENVI format file and the appropriate value will be included in the “data ignore value” tag in the ENVI header file.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

filename<-'Z:/filename.dtm'
DTMHeader(filename = filename)

XYZ2DTM

Description

XYZ2DTM converts surface models stored as ACSII XYZ point files into the PLANS DTM format. Input point files include one record for each grid point with the X, Y, and elevation values separated by commas, spaces, or tabs. In general, this utility is only used when surface models are delivered in this format. FUSION provides the ability to export a PLANS DTM model in XYZ point format but this format is not the most efficient in terms of storage space. In addition, most GIS packages cannot directly convert this format into a surface model. They often use the XYZ points as if they were random XYZ data and interpolate a new grid using the point data. XYZ2DTM offers an optional switch to fill void areas by interpolating from surrounding grid elevations.

Usage

XYZ2DTM(
  fusion.path = "C:/FUSION/",
  surfacefile,
  xyunits,
  zunits,
  coordsys,
  zone,
  horizdatum,
  vertdatum,
  datafile1,
  datafile2 = NULL,
  switches = FALSE
)

Arguments

fusion.path

Character. By default: C:/FUSION/. Path where the program FUSION is installed.

surfacefile

is a character.Name for output canopy surface file (stored in PLANS DTM format with .dtm extension).

xyunits

Character. Units for LIDAR data XY:

  • M - for meters.

  • F - for feet.

zunits

Character. Units for LIDAR data elevations:

  • M - for meters.

  • F - for feet.

coordsys

Numeric. Coordinate system for the canopy model:

  • 0 - for unknown.

  • 1 - for UTM.

  • 2 - for state plane.

zone

Numeric.. Coordinate system zone for the canopy model (0 for unknown).

horizdatum

is a numeric. Horizontal datum for the canopy model.

  • 0 - for unknown.

  • 1 - for NAD27.

  • 2 -for NAD83.

vertdatum

Character..Vertical datum for the surface

  • 0 - for unknown.

  • 1 - for NGVD29.

  • 2 -for NAVD88.

  • 3 -for GRS80.

datafile1

Character. First XYZ point file...may be wildcard or text list file (extension .txt only)...omit other datafile# parameters. Second XYZ point file.

datafile2

Character.NULL by default. Second XYZ point file. Several point files can be specified. The limit depends on the length of each file name. When using multiple data files, it is best to use a wildcard for datafile1 or create a text file containing a list of the data files and specifying the list file as datafile1.

switches

False as default. To insert a switch, it must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value (numeric).

  • /csv - Input files are in CSV format, skip first line when reading.

  • /fillholes:# - Fill holes (NODATA areas) in the final surface model that are up to # by # cells. Larger holes will not be filled

Details

XYZ2DTM scans all data files to determine the extent of the final surface model and the grid cell size. XYZ data files should be ordered in either rows or columns for the cell size detection logic to work correctly. XYZ2DTM will not work with random XYZ point data. Prior to populating the surface with grid elevations, all grid points are initialized to indicate NODATA (value of -1.0). As XYZ point files are read and processed, grid cell elevations are inserted into the appropriate row/column location. After all XYZ point files have been processed, the model is written using the PLANS DTM file format with floating point elevation values.
When the /fillholes:# switch is specified. Void areas in the final surface are filled by interpolating values from adjacent grid cells. The parameter, #, specifies the largest distance that will be searched for valid point elevations. In operation, the void filling logic searches in eight directions to find valid grid point elevations to use in the interpolation. If four or more of the directional searches find a valid elevation, the hole is filled using the average of all the values.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

surfacefile<-'Z:/dtmfile.dtm'
datafile1<- 'Z:/datafile1.xyz'
XYZ2DTM(surfacefile = surfacefile,xyunits = 'M',zunits = 'M',
          coordsys = 1,zone = 0, horizdatum = 0, vertdatum = 0,
                    datafile1=datafile1, switches = FALSE)

filterData

Description

FilterData applies various filters to return data files to produce new return data files with only the returns that meet the filter requirements. The most common application for FilterType is to remove “outliers” from return data files. Other filter options overlay the return data with a user-specified grid and produce output return files that contain only the returns with the minimum or maximum elevation for each grid cell.

Usage

filterData(
  fusion.path = "C:/FUSION/",
  FilterType,
  FilterParms,
  WindowSize,
  OutputFile,
  DataFile,
  switches = NULL
)

Arguments

fusion.path

Character. The directory where FUSION is installed. By defult: C:/FUSION/

FilterType

Character. Filtering algorithm used to remove returns from the DataFile(s).
The following options (by name) are supported:

  • outlier - removes returns above or below the mean elevation plus or minus FilterParms * standard deviation of the elevations

  • outlier2 - More robust outlier removal (experimental)

  • minimum - removes all returns except the return with the minimum elevation

  • maximum - removes all returns except the return with the maximum elevation

FilterParms

Numeric. Parameters specific to the filtering method. For outlier this is the multiplier applied to the standard deviation. For minimum and maximum, FilterParms is ignored (but a value must be included on the command line...use 0)

WindowSize

Numeric. Size of the window used to compute the standard deviation of elevations or the minimum/maximum return

OutputFile

Character. Name of the output file. If any part of the name includes spaces, include the entire name in double quotation marks. Must have the extension.

DataFile

Character. LIDAR data file name or template or name of a text file containing a list of file names (list file must have .txt extension).

switches

Character. Default is NULL. To insert a switch, each switch must have a '/' before of the names. If you want to insert two or more switches, they must be separated by an empty space. When a # is displayed, should be replaced by the desired value depending on see switch.

  • /lda - Write output files using FUSION's LDA format when using LAS input files. The default behavior after FUSION version 3.00 is to write data in LAS format when the input data are in LAS format. When using input data in a format other than LAS, sample files are written in LDA format.

  • /layers - Output intermediate raster data layers.

  • /index - Create FUSION index files for the output file.

  • /invert - Inverts the elevations for points so the logic will work for points below ground. Use with outlier2.

  • /minsd:# - Minimum standard deviation for points within a comparison window for filtering to take place. Default is 1.0 (same units as elevation data). This switch is only useful when using the outlier filter.

  • /minpts:# - Minimum number of points in the comparison window for filtering to take place. This option can be used with all filters but must specify at least 3 points when used with the outlier filter.

  • /minrange:# - Minimum range in elevations within a window for outlier filtering to take place. Default is 150.0 elevation units Used only with the outlier2 filter.

  • /mingap:# - Minimum vertical distance that define a gap. Used to isolate points above the majority of points in the filter window. Used only with the outlier2 filter

  • /gapratio:# - Proportion of points in window that can be above a vertical gap. Ranges from 0.0 to 1.0 Used only with the outlier2 filter.

  • /class:string - Used with LAS format files only. Specifies that only points with classification values listed are to be included in the subsample. Classification values should be separated by a comma e.g. (2,3,4,5) and can range from 0 to 31. If the first character of string is “~”, all classes except those listed will be used.

  • /ignoreoverlap - Ignore points with the overlap flag set (LAX V1.4+ format).

  • /precision:scaleX,scaleY,scaleZ - Control the scale factor used for X, Y, and Z values in output LAS files. These values will override the values in the source LAS files. There is rarely any need for the scale parameters to be smaller than 0.001.

  • /reclass:# - Change the classification code for points identified as outliers and write them to the output file. The optional value is the classification code assigned to the points. Only valid when used with the outlier and outlier2 filters. The code must be between brackets.

Details

FilterData was developed to help LIDAR data users eliminate outliers from files delivered by vendors. In general, vendors identify outliers (returns above expected elevations for vegetation and structures or returns below the ground surface) and either use the LAS classification field to label the return as an outlier or delete them from the files delivered to their client. However, sometimes not all outliers are removed. The presence of unlabeled outliers can cause problems for bare-earth filtering algorithms and vegetation analysis as well as other analyses. FilterData offers a way for the data user to produce “clean” data files for use in subsequent analyses.
FilterData provides an outlier filter that identifies and removes returns based on the range of observed elevation values in the comparison window. In operation, the outlier filter works by computing the mean elevation and standard deviation of elevations for each cell in the comparison grid. Then, individual return elevations are compared to range defined as follows:

mean elevation ± (FilterParms * ElevationStandardDeviation)


Only returns with elevations within the range are written to the output file. Generally, using a range of ± 5.0 * Standard deviation and a large window size (100 m) eliminates most outliers. In areas if steep terrain with returns from birds, a range of ± 3 * Standard deviation may produce better results. The outlier filter can also be used on return files produced using the maximum filter to eliminate high returns from small objects such as transmission towers and lines. Flat areas with no above-ground features can result in a very low standard deviation of the return elevations. For data files containing such areas, it may be necessary to use the /minsd:# switch to control filtering in cells with small standard deviations. The default is to use a minimum threshold standard deviation of 1.0 (same units as the return elevations). For most areas, this will be sufficient. If you specify a smaller threshold, you may find that all returns within the comparison window are removed.
FilterData also provides a minimum and maximum classification feature that produces output files that contain only the return with the minimum or maximum elevations for each cell in the comparison grid.

Value

No return value. This function return the command prompt running the FUSION command

References

McGaughey, R.J. FUSION/LDV: Software for LIDAR Data Analysis and Visualization. 2021.

Examples

filterData(FilterType = 'outlier2',FilterParms = 3,WindowSize =  5,
OutputFile = 'Z:/filterdata.las',DataFile = 'Z:/datafile.las', switches = '/invert /layers')