Module Translate
See Also
opals::ITranslate

Aim of module

Performs format conversion for vector data files with additional read support of GDAL rasters.

General description

Module Translate is a tool providing data format conversion functionality. Up to now, it supports the reading/writing of vector data formats (LAS, ESRI Shapefile, ODM, ASCII /binary, etc.). In the longer perspective Module Translate will also support raster file conversion and coordinate system transformations.

The main parameters are a single or multiple input file names (inFile) and the output file name (outFile). The respective data format is automatically estimated based on the file contents (input) and/or extension (output) but can also be defined explicitly (iFormat, oFormat). In both cases, well defined standard formats as described in Supported data formats as well as arbitrary ascii or binary data formats based on OPALS Format Definition XML files are supported. In case that no output format is specified, the output file is created using the file format and structure of the input file. This is especially useful if only a subset of the data should be written to the output by specifying a filter. For details on filters and how they are defined please refer to the Filter manual. Please note that, in contrast to Module Import only a single input format is supported. Thus, if multiple input files are specified, all files must share the same data format.

An additional functionality of Module Translate is the application of a 3D affine transformation (trafo) in the course of file format conversion. The transformation parameters are typically computed by other OPALS modules like opalsLSM, opalsICP, or opalsGeorefApprox.

Furthermore, Module Translate supports splitting of the input file contents into separate output files based on a specific attribute of the dataset splitbyAttribute. This feature is, e.g., useful to extract the original flight strips from tiled datasets via a strip identifier (e.g. PointSourceId, cf. Example 5:) or to divide a multi-return dataset into 1st, 2nd, ..., nth echo data files (EchoNumber, cf. Example 4:). While the feature is supported for all numeric types, integer-valued attributes constitute the standard usage case. For each distinct attribute value, a separate file is created. Please note that real-valued attributes (float, double) are automatically casted to integer.

Parameter description

-inFileinput file(s)
Type: opals::Vector<opals::Path>
Remarks: mandatory
Import vector data file.
-outFileoutput file name
Type: opals::Path
Remarks: estimable
Estimation rule: The current path and the name (body) of the (first) input file is used as file name basis (stem). Depending on the number of input files and whether of not -splitByAttribute is specified, the output file is named as follows:
nr. inFiles==1 and splitByAttribute=no : stem + '.translatedTo' + oFormat extension
nr. inFiles >1 and splitByAttribute=no : stem + '.multipleInputsTranslatedTo' + oFormat extension
splitByAttribute=yes : stem + '_' + name-of-attribute name + '_' + value-of-attribute + oFormat extension
In the latter case, value-of-attribute denotes the unique values of the splitting attribute found in the input datasets.
-iFormatfile format [auto, xyz, bxyz, wnp, bwnp, las, sdw, fwf, odm, <opals format def. xml file>]
Type: opals::String
Remarks: default=auto
Input file format. If no format is specified the file content is used to recognise the file format.
-oFormatoutput format [xyz, bxyz, wnp, bwnp, las, sdw, fwf, odm, <opals format def. xml file>]
Type: opals::String
Remarks: optional
Defines the output format. If not specified, the output file written in the very same format as the input file.
-filtermodify the input using a (tree of) filter(s)
Type: opals::String
Remarks: optional
A filter string in EBNF syntax as described in section 'Filter syntax' can be passed to restrict the input data set (e.g. to consider last echoes only)
-trafogeometrically transform the data during import
Type: opals::TrafPars3dAffine
Remarks: optional
An eventually passed affine 3-d transformation is applied during data import. The passed value is converted internally into a single filter tree for parameters 'filter' and 'trafo'. If both are to be used, make sure to mark the position where in the filter's string 'trafo' shall be introduced, using curly brackets {}
-splitByAttributesplit attribute
Type: opals::String
Remarks: optional
If specified, the output is split into individual files based on the respecive attribute. This can, e.g., be used to separate flight strips from tiled data using the PointSouceId attribute or to separate the 1st, 2nd, etc. echoes based on the EchoNumber attribute. Please note that this works only for numerical attributes but not for strings. Furthermore, all numerical attributes are automatically converted (i.e. casted) to integer.

Examples

The data used in the following examples can be found in the $OPALS_ROOT/demo/ directory.

Example 1:

opalsTranslate -inFile strip31.laz -oFormat fwf

The above command converts the file strip31.laz from compressed LAS file format to the ASCII file strip31.laz.convertedTo.fwf. The attributes Amplitude (i.e. LAS intensity), EchoNumber, and NrOfEchos are preserved as they are contained in the predefined FWF format. Please note that the name of the output file is automatically estimated based on the respective estimation rule.

Example 2:

opalsTranslate -inFile strip31.laz -iFormat LAS_1.2_ew.xml -oFormat fwf

Providing the proper input format definition XML file LAS_1.2._ew.xml which maps the LAS extry byte attribute PulseWidth to the predefined OPALS Datamanager attribute EchoWidth additionally preserves the echo width information in the ASCII output file.

Example 3:

opalsTranslate -inFile strip31.laz -outFile strip31-intermed.bxyz -filter echo[intermediate]

This command reads the LAS file, analyses the echo attributes via the specified filter, and writes all intermediate echo points to a binary XYZ file.

Example 4:

This example demonstrates the usage of splitByAttribute to extract the 1st, 2nd, ..., nth echo from multiple input files.

opalsTranslate -inFile strip?1.laz -outFile echo.las -splitByAttr EchoNumber

As a result, seven files named echo_1.las to echo_7.las are created corresponding to the unique echo numbers of the input datasets. Please note that it is not necessary to know the attribute range beforehand, as the uniqueness is checked for each point and new output files are automatically created if needed.

Example 5:

This example illustrates the usage of splitByAttribute to extract the flight strips from an entire flight block dataset based on the attribute PointSourceId.

opalsImport -inFile strip?1.laz -outFile strips.odm -tileSize 25
opalsTranslate -inFile strips.odm -splitByAttr PointSourceId

Please note that in this example no output file name is specified. Module Translate automatically composes the output file names from the name of the input file (strips_), the attribute name (PointSourceId_) and the unique PointSourceId values (11, 21, 31). The following files are hence exported.

strips_PointSourceId_11.odm
strips_PointSourceId_21.odm
strips_PointSourceId_31.odm

Current restrictions:

Currently only point datasets are supported, when running Module Translate with splitByAttribute.

Author
G. Mandlburger
Date
13.04.2018