Python script preCalcFootprint
See also

Aim of script

Calculates the axes of the laser footprint on the target using a trigonometric approach.

The aim of preCalcFootprint is to calculate the laser footprint area.

General description

Using either existing normal and beam vectors (odm-attributes) or getting them on-the-fly, the ellipse can be calculated either as points with attributes (area, semimajor axis, ...) or as a polygon approximating the shape. Output can either be an odm or a shape file.

See also
Python script preCalcFootprint

The intersection area of a laser beam with the tangent plane of a target surface is commonly referred to as laser footprint. It's size depends on the range (sensor-to-target distance), the beam divergence (i.e. opening angle of the laser beam) and the incidence angle between the beam and the surface. The latter is calculated based on the laser beam direction and the surface normal vector.

Output can be either points or polygons, and either opals Datamanager (odm) or ESRI Shapefile (.shp). Different attributes can be selected for string by using the {-a, –attribute} parameter. In case of angles of incidence close to 90°, resulting ellipses will not be exact. To skip those automatically, the {–m, –max_incidence} parameter can be used.

Basic algorithm

The script uses a trigonometric approach to calculate the semimajor and semiminor axes of the theoretical elliptic footprint of the laser beam. In the next step, coordinates for points on this ellipse are calculated, with the ellipse in standard form and the points spaced apart {–pointspacing} degrees (eccentric anomaly). These points are then transformed into their position on the tangent plane.

Parameter description

-inFile input DataManager file (*.odm)
Type : PathArgument
Remark : Mandatory
-outFile output file (.odm/.shp)
Type : PathArgument
Remark : Optional
Description: Polygon output file. If extension (.odm/.shp) is provided, the respective format will be used. Default format is .shp. If no outFile is given, results will be written back to the -inFile odm.
-filter dataManager filter for pre-selection of points (not implemented yet
Type : String
Remark : Optional
-limits format: "xmin xmax ymin ymax"
Type : String
Remark : Optional
-beamDivergence divergence of the laser beam in [mrad]
Type : Floating-point number
Remark : Mandatory
-trjFile path to the file containing the trajectory (if BeamVector Arguments are not set)
Type : PathArgument
Remark : Optional
-trjFormat format description to be used for parsing the input trajectory. This will be passed to the opalsImport module.
Type : String
Remark : Optional
-pointSpacing spacing between points for resulting ellipse polygon in [deg] (only if 'geometry polygon' is selected
Type : Floating-point number
Remark : Optional, default: 10
-attributes specify which features (multiple options allowed) should be saved to the output file
Type : String
Remark : Optional, default: ['area']
Description: to save multiple features use this option multiple times e.g. -attr area -attr axes
Possible values:
areasaves the area of the footprint as attribute [in sq.m.]
semimajorsaves the semimajor axis [in m]
semiminorsaves the semiminor axis [in m]
axessaves both axes [in m]
incidencesaves the angle of incidence [in rad]
pointidsaves the id of the originating point
beamvectorsaves the X/Y/Z components of the beam vector
normalvectorsaves the X/Y/Z components of the normal vector
-geometry output geometry type: point or polygon: polygons approximate the ellipse of the laser footprint
Type : String
Remark : Optional, default: 'polygon'
Possible values:
-maxIncidence maximum incidence angle for footprint calculation [deg]
Type : Floating-point number
Remark : Optional, default: 90


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

As a prerequisite for the subsequent examples, please import the data using the following command:

opalsImport -inFile strip11.laz -trjFile TrjStrips_utm33.txt -tFormat trajectory.xml -storeBeamInfo BeamVector -filter "region[529570 5338660 529610 5338720]"
opalsNormals -inFile strip11.odm -searchMode d3 -neigh 8 -searchR 1.5

Example 1

Calculate ellipse area and axes, store them in a polygon shapefile. Beam- and normal vectors are assumed as attributes.

opals preCalcFootprint -i strip11.odm -a area -a axes -o polygon_footprints.shp -beamdivergence 0.25

Example 2

Calculate beam vectors "on-the-fly", and save the result in an odm as points (with attributes)

opals preCalcFootprint -i strip11.odm -a area -a incidence -o footprint.odm -trjFile TrjStrips_utm33.txt -trjFormat trajectory.xml -g point -beamdivergence 0.25

Example 3

Write polygon information back to the original odm. Beam vectors are, again, assumed. The polygons will have the origninating point id and the three components of the beam vector as attributes.

opals preCalcFootprint -i strip11.odm -a pointid -a beamvector -beamdivergence 0.25


opalsNormals is the executable file of Module Normals
Definition: ModuleExecutables.hpp:148
@ trajectory
strip.trajectory group (opalsStripAdjust)
@ tFormat
file format of the trajectory file (opalsImport)
opalsImport is the executable file of Module Import
Definition: ModuleExecutables.hpp:113
Contains the public interface of OPALS.
Definition: ApplyTrafo.hpp:5
@ point
pixel (center) represents a point, mainly used for DTM grids
@ BeamVector
Beam vector in the world coordinate system.
@ filter
string to be parsed in construction of DM::IFilter (various modules)
@ area
Calculate only the area.
@ storeBeamInfo
defines beam information that is attached during import (opalsImport)
@ searchMode
dimension of nearest neighbor search (opalsNormals)
@ d3
Search based on full 3D coordinates (x,y and z)