16.54. pc_align

The pc_align programs aligns two point clouds. The supported algorithms are Iterative Closest Point (Section 16.54.3.1), Nuth and Kaab (Section 16.54.3.2), Fast Global Registration (Section 16.54.3.3), and feature-based alignment (Section 16.54.3.4).

Some of the provided ICP implementations can handle a scale change, in addition to rotations and translations.

Usage:

pc_align --max-displacement <float> [other options]    \
  <reference cloud> <source cloud> -o <output prefix>}

The denser cloud must be the first one to be passed to this tool. This program is very sensitive to the value of --max-displacement (Section 16.54.2).

An example is in Section 6.1.11. Validation and error metrics are discussed in Section 16.54.10 and Section 16.54.9.

See the related program image_align (Section 16.33).

Several important things need to be kept in mind if pc_align is to be used successfully and give accurate results, as described below.

16.54.1. The input point clouds

Due to the nature of ICP, the first input point cloud, that is, the reference (fixed) cloud, should be denser than the second, source (movable) point cloud, to get the most accurate results. This is not a serious restriction, as one can perform the alignment this way and then simply invert the obtained transform if desired (pc_align outputs both the direct and inverse transform, and can output the reference point cloud transformed to match the source and vice-versa).

The user can choose how many points to pick from the reference and source point clouds to perform the alignment. The amount of memory and processing time used by pc_align is directly proportional to these numbers, ideally the more points the better. Pre-cropping to judiciously chosen regions may improve the accuracy and/or run-time.

16.54.2. The max displacement option

In many typical applications, the source and reference point clouds are already roughly aligned, but the source point cloud may cover a larger area than the reference. The user should provide to pc_align the expected maximum distance (displacement) source points may move by as result of alignment, using the option --max-displacement.

This number will help remove source points too far from the reference point cloud which may not match successfully and may degrade the accuracy. If in doubt, this value can be set to something large but still reasonable, as the tool is able to throw away a certain number of unmatched outliers.

At the end of alignment, pc_align will display the observed maximum displacement, a multiple of which can be used to seed the tool in a subsequent run. If an initial transform is applied to the source cloud (Section 16.54.6), the outliers are thrown out after this operation. The observed maximum displacement is also between the source points with this transform applied and the source points after alignment to the reference.

16.54.3. Alignment method

The alignment method can be set with the option --alignment-method (Section 16.54.16). The default is point-to-plane ICP.

16.54.3.1. ICP algorithms

ASP provides several flavors of the Iterative Closest Point (ICP) algorithm, with the implementation given by the libpointmatcher library ([PCSM13]).

The default alignment method is Point-to-Plane ICP, which may be more robust to large translations than Point-to-Point ICP, though the latter can be good enough if the input point clouds have small alignment errors and it is faster and uses less memory as well. The tool also accepts an option named --highest-accuracy which will compute the normals for Point-to-Plane ICP at all points rather than about a tenth of them. This option is not necessary most of the time, but may result in better alignment at the expense of using more memory and processing time.

The default alignment transform is rigid, that is, a combination of rotation and translation. It is also possible to solve for a scale change, by setting --alignment-method to similarity-point-to-plane or similarity-point-to-point. The first of these works better than the second one.

If the translation between the point clouds is very large, see Section 16.54.3.4.

16.54.3.2. Nuth and Kaab

The Nuth and Kaab alignment method ([NKaab11]) can be sub-grid-size accurate. It is accessible with --alignment-method nuth. The implementation is based on dem_align.py.

It is assumed that:

• The input clouds are dense and detailed DEMs with notable relief

• The DEMs have a lot of overlap

• The alignment transform is a pure translation in projected coordinates (both horizontal and vertical).

If the last two assumptions do not hold, consider using a different alignment algorithm first (for example, feature-based alignment in combination with ICP, Section 16.54.3.4). The resulting aligned source point cloud needs to be regridded with point2dem, and then the alignment further refined with this method.

The order of inputs should be so that the reference DEM (the first input) has a grid size that is no bigger than of the second DEM. The second DEM will be interpolated to the grid of the first one.

Both DEMs should be in projected coordinates, so with the grid size measured in meters, and with the same datum. Otherwise, regridding can be done with gdalwarp -r cubic (Section 16.25). LAS files can be regridded with point2dem (Section 16.57).

The produced alignment transform will be converted to a rotation + translation transform around the planet center (ECEF coordinates), for consistency with the other alignment methods. It will be an ECEF translation if the option --compute-translation-only is set.

The DEMs should fit fully in memory, with a solid margin.

Large DEMs with good relief could be regridded (with cubic interpolation) to a 2x coarser grid, which would still result in a good alignment. That goes as follows, for any input DEM:

gdal_translate -r average -outsize 50% 50% input.tif output.tif

Any produced transform with lower-resolution DEMs can be applied to the original DEMs (Section 16.54.6).

Additional options can be passed in via --nuth-options (Section 16.54.17).

This alignment method does not support the --initial-transform option, because it computes the alignment transform in projected coordinates of the reference DEM, and in that space an external ECEF transform cannot be applied exactly.

16.54.3.3. FGR algorithm

The Fast Global Registration (FGR) algorithm can be called with --alignment-method fgr, and is customizable via --fgr-options (Section 16.54.16).

This approach can perform better than ICP when the clouds are close enough to each other but there is a large number of outliers, since it does a cross-check.

When the clouds are far, another algorithm can be employed to bring them closer first (Section 16.54.6).

16.54.3.4. Feature-based alignment

If the clouds differ by a large translation or scale factor, alignment can fail. If the clouds are DEMs, one may specify the option --initial-transform-from-hillshading which will hillshade the two DEMs, find interest point matches among them, and use that to compute an initial transform between the clouds, which may or may not contain scale.

This transform can be passed as an initial guess to the other alignment algorithms (Section 16.54.6). See an example in Section 8.24.9.

The related correlation-based alignment method is described in Section 16.54.3.5.

This functionality is implemented with ASP’s hillshade, ipfind, and ipmatch tools. The pc_align options --hillshade-options, --ipfind-options, and --ipmatch-options can be used to pass options to to these programs, such as to increase the number interest points being found, if the defaults are not sufficient. See Section 16.54.16.

The match file having the correspondences between the two hillshaded DEMs is saved in the output directory and can be inspected. It can also be created or edited manually (Section 16.54.12).

If the two clouds look too different for interest point matching to work, they perhaps can be re-gridded to use the same (coarser) grid, as described in Section 16.54.13. The produced transform will be applicable to the original clouds.

16.54.3.5. Correlation-based alignment

Given two DEMs with the same grid size that look visually similar when hillshaded, the dense image correlation can be found between the hillshaded images, and that can be employed to align the clouds. That goes as follows.

Hillshading happens with the hillshade program (Section 16.28):

hillshade ref.tif -o ref_hill.tif
hillshade src.tif -o src_hill.tif

Image correlation is performed (Section 16.17):

parallel_stereo --correlator-mode    \
  --ip-per-image 40000               \
  ref_hill.tif src_hill.tif          \
  --num-matches-from-disparity 40000 \
  run_corr/run

Stereo correlation can take a long time. It can be run over several nodes (Section 8.16). The option --max-disp-spread can help with reducing the search range (Section 17.2). A value like 50 is likely adequate.

This produces a dense match file (Section 12.2.4.2), that can be passed to pc_align:

matchFile=run_corr/run-disp-ref_hill__src_hill.match
pc_align                                     \
  --max-displacement -1                      \
  --num-iterations 0                         \
  --max-num-reference-points 1000000         \
  --match-file $matchFile                    \
  --initial-transform-from-hillshading rigid \
  --initial-transform-ransac-params 1000 3   \
  --save-transformed-source-points           \
  ref.tif src.tif                            \
  -o run_align/run

The resulting aligned cloud run_align/run-trans_source.tif can be regridded with point2dem and same grid size and projection as the input DEMs, and evaluate if it moved as expected.

This method will fail if the input DEMs do not overlap a lot when overlaid with georeference information.

The related method in Section 16.54.3.4 uses sparse features from hillshading, and can handle a large translation between the clouds.

16.54.3.6. Least squares

Another option is to use least squares (with outlier handling using a robust cost function) to find the transform, if the reference cloud is a DEM. This is an experimental mode that is not recommended.

For this, one should specify the alignment method as least-squares or similarity-least-squares (the latter also solves for scale). It is suggested that the input clouds be very close or otherwise the --initial-transform option be used, for the method to converge, and use perhaps on the order of 10-20 iterations and a smaller value for --max-num-source-points (perhaps a few thousand) for this approach to converge reasonably fast.

16.54.4. File formats

The input point clouds can be in one of several formats: ASP’s point cloud format (the output of stereo), DEMs as GeoTIFF or ISIS cub files, LAS files, or plain-text CSV files (with .csv or .txt extension).

By default, CSV files are expected to have on each line the latitude and longitude (in degrees), and the height above the datum (in meters), separated by commas or spaces. Alternatively, the user can specify the format of the CSV file via the --csv-format option. Entries in the CSV file can then be (in any order) (a) longitude, latitude (in degrees), height above datum (in meters), (b) longitude, latitude, distance from planet center (in meters or km), (c) easting, northing and height above datum (in meters), in this case a PROJ or WKT string must be set via --csv-srs, (d) Cartesian coordinates \((x, y, z)\) measured from planet center (in meters). The precise syntax is described in the table below. The tool can also auto-detect the LOLA RDR PointPerRow format.

Any line in a CSV file starting with the pound character (#) is ignored.

If none of the input files have a geoheader with datum information, and the input files are not in Cartesian coordinates, the datum needs to be specified via the --datum option, or by setting --semi-major-axis and --semi-minor-axis.

16.54.5. The alignment transform

The transform obtained by pc_align is output to a text file as a 4 × 4 matrix with the upper-left 3 × 3 submatrix being the rotation (and potentially also a scale, per Section 16.54.3) and the top three elements of the right-most column being the translation. It is named <output prefix>-transform.txt.

This transform, if applied to the source point cloud, will bring it in alignment with the reference point cloud. The transform assumes the 3D Cartesian coordinate system with the origin at the planet center (known as ECEF). This matrix can be supplied back to the tool as an initial guess (Section 16.54.6).

The inverse transform, from the reference cloud to the source cloud is saved as well, as <output prefix>-inverse-transform.txt.

These two transforms can be used to move cameras from one cloud’s coordinate system to another one’s, as shown in Section 16.54.14.

16.54.6. Applying an initial transform

The pc_align-produced transform (Section 16.54.5) can be supplied back to the tool as an initial guess via the --initial-transform option, with the same clouds as earlier, or some supersets or subsets of them. If it is desired to apply this transform without further refinement, one can specify --num-iterations 0.

An initial transform can be found, for example, based on hillshading the two clouds (Section 16.54.3.4).

To illustrate applying a transform, consider a DEM, named dem.tif, obtained with ASP, from which just a portion, dem_crop.tif is known to have reliable measurements, which are stored, for example, in a file called meas.csv. Hence, pc_align is first used on the smaller DEM, as:

pc_align <other options> dem_crop.tif meas.csv -o run/run

Then, the command:

pc_align                                    \
  --max-displacement -1                     \
  --num-iterations 0                        \
  --max-num-reference-points 1000           \
  --max-num-source-points 1000              \
  --save-transformed-source-points          \
  --save-inv-transformed-reference-points   \
  --initial-transform run/run-transform.txt \
  --csv-format <csv format string>          \
  dem.tif meas.csv                          \
  -o run_full/run

will transform the full dem.tif into the coordinate system of meas.csv, and meas.csv into the coordinate system of ref.tif with no further iterations. The number of input points here is small, for speed, as they will not be used.

See also Section 16.54.14 for how to use such transforms with cameras.

If an initial transform is used, with zero or more iterations, the output transform produced by such an invocation will be from the source points before the initial transform, hence the output alignment transform will incorporate the initial transform.

Using --max-displacement -1 should be avoided, as that will do no outlier filtering in the source cloud. Here that is not necessary, as this invocation simply moves the DEM according to the specified transform.

If a good initial alignment is found, it is suggested to use a smaller value for --max-displacement to refine the alignment, as the clouds will already be mostly on top of each other after the initial transform is applied.

16.54.7. Applying an initial specified translation or rotation

One can apply to the source cloud an initial shift, expressed in the North-East-Down coordinate system at the centroid of the source points, before the alignment algorithm is invoked. Hence, if it is desired to first move the source cloud North by 5 m, East by 10 m, and down by 15 m relative to the point on planet surface which is the centroid of the source points, the continue with alignment, one can invoke pc_align with:

--initial-ned-translation "5 10 15"

(Notice the quotes.)

The option --initial-rotation-angle can be used analogously.

As in Section 16.54.6, one can simply stop after such an operation, if using zero iterations. In either case, such initial transform will be incorporated into the transform file output by pc_align, hence that one will go from the source cloud before user’s initial transform to the reference cloud.

16.54.8. Interpreting the transform

The alignment transform, with its origin at the center of the planet, can result in large movements on the planet surface even for small angles of rotation. Because of this it may be difficult to interpret both its rotation and translation components.

The pc_align program outputs the translation component of this transform, defined as the vector from the centroid of the original source points (before any initial transform applied to them) to the centroid of the source points with the computed alignment transform applied to them. This translation component is displayed in three ways (a) Cartesian coordinates with the origin at the planet center, (b) Local North-East-Down coordinates at the centroid of the source points (before any initial transform), and (c) Latitude-Longitude-Height differences between the two centroids. If the effect of the transform is small (e.g., the points moved by at most several hundred meters) then the representation in the form (b) above is most amenable to interpretation as it is in respect to cardinal directions and height above ground if standing at a point on the planet surface.

This program prints to screen the Euler angles of the rotation transform, and also the axis of rotation and the angle measured against that axis. It can be convenient to interpret the rotation as being around the center of gravity of the reference cloud, even though it was computed as a rotation around the planet center, since changing the point around which a rigid transform is applied will only affect its translation component, which is relative to that point, but not the rotation matrix.

16.54.9. Error metrics and outliers

The tool outputs to CSV files the lists of errors together with their locations in the source point cloud, before the alignment of the source points (but after applying any initial transform), and also after the alignment computed by the tool. They are named <output prefix>-beg_errors.csv and <output prefix>-end_errors.csv. An error is defined as the distance from a source point used in alignment to the closest reference point (measured in meters).

The format of output CSV files is the same as of input CSV files, or as given by --csv-format, although any columns of extraneous data in the input files are not saved on output. The first line in these files shows the names of the columns.

See Section 16.70.6 for how to visualize these files. By default, this tool shows the 4th column in these files, which is the absolute error difference. Run, for example:

stereo_gui --colorbar run/run-end_errors.csv

The program prints to screen and saves to a log file the 16th, 50th, and 84th error percentiles as well as the means of the smallest 25%, 50%, 75%, and 100% of the errors.

When the reference point cloud is a DEM, a more accurate computation of the errors from source points to the reference cloud is used. A source point is projected onto the datum of the reference DEM, its longitude and latitude are found, then the DEM height at that position is interpolated. That way we determine the closest point on the reference DEM that interprets the DEM not just as a collection of points but rather as a polyhedral surface going through those points. These errors are what is printed in the statistics. To instead compute errors as done for other type of point clouds, use the option --no-dem-distances.

By default, when pc_align discards outliers during the computation of the alignment transform, it keeps the 75% of the points with the smallest errors. As such, a way of judging the effectiveness of the tool is to look at the mean of the smallest 75% of the errors before and after alignment.

16.54.10. Evaluation of aligned clouds

The pc_align program can save the source cloud after being aligned to the reference cloud and vice-versa, via --save-transformed-source-points and --save-inv-transformed-reference-points.

To validate that the aligned source cloud is very close to the reference cloud, DEMs can be made out of them with point2dem (Section 16.57), and those can be overlaid as georeferenced images in stereo_gui (Section 16.70) for inspection. A GIS tool can be used as well.

Alternatively, the geodiff program (Section 16.26) can compute the (absolute) difference between aligned DEMs, which can be colorized with colormap (Section 16.14), or colorized on-the-fly and displayed with a colorbar in stereo_gui (Section 16.70.5).

The geodiff tool can take the difference between a DEM and a CSV file as well. The obtained error differences can be visualized in stereo_gui (Section 16.70.6).

16.54.11. Output point clouds and convergence history

The transformed input point clouds (the source transformed to match the reference, and the reference transformed to match the source) can also be saved to disk if desired. If an input point cloud is in CSV, ASP point cloud format, or LAS format, the output transformed cloud will be in the same format. If the input is a DEM, the output will be an ASP point cloud, since a gridded point cloud may not stay so after a 3D transform.

As an example, assume that pc_align is run as:

pc_align --max-displacement 100              \
  --csv-format '1:x 2:y 3:z'                 \
  --save-transformed-source-points           \
  --save-inv-transformed-reference-points    \
  ref_dem.tif source.csv                     \
  -o run/run

This will save run/run-trans_reference.tif which is a point cloud in the coordinate system of the source dataset, and run/run-trans_source.csv which is in reference coordinate system of the reference dataset.

The point2dem program (Section 16.57) can re-grid the obtained point cloud back to a DEM.

Care is needed, as before, with setting --max-displacement.

The convergence history for pc_align (the translation and rotation change at each iteration) is saved to disk with a name like:

<output prefix>-iterationInfo.csv

and can be used to fine-tune the stopping criteria.

16.54.12. Manual alignment

If automatic alignment fails, for example, if the clouds are too different, or they differ by a scale factor, a manual alignment can be computed as an initial guess transform (and one can stop there if pc_align is invoked with 0 iterations).

For that, the input point clouds should be first converted to DEMs using point2dem, unless in that format already. Then, stereo_gui can be called to create manual point correspondences (interest point matches) from the reference to the source DEM (Section 16.70.11). The DEMs should be displayed in the GUI with the reference DEM on the left, and should be hillshaded.

Once the match file is saved to disk, it can be passed to pc_align via the --match-file option, which will compute an initial transform (whose type is set with --initial-transform-from-hillshading), before continuing with alignment. This transform can also be used for non-DEM clouds once it is found using DEMs obtained from those clouds. Note that both a rigid and similarity transform is supported, both for the initial transform and for the alignment.

16.54.13. Regrid a DEM

Given a DEM, if one invokes pc_align as follows:

pc_align dem.tif dem.tif --max-displacement -1 --num-iterations 0 \
   --save-transformed-source-points -o run/run

this will create a point cloud out of the DEM. This cloud can then be re-gridded using point2dem (Section 16.57), with desired grid size and projection.

Alternatively, the gdalwarp program (Section 16.25) can be employed for regridding, with an option such as -r cubic.

The point2dem approach is preferable if the output grid size is very coarse, as this tool does binning in a neighborhood, rather than interpolation.

16.54.14. Applying a transform to cameras

If pc_align is used to align a DEM obtained with ASP to a preexisting reference DEM or other cloud, the obtained alignment transform can be applied to the cameras used to create the ASP DEM, so the cameras then become aligned with the reference. That is accomplished by running bundle adjustment with the options --initial-transform and --apply-initial-transform-only.

Please note that the way this transform is applied depends on the order of clouds in pc_align and on whether the cameras have been bundle-adjusted or not. Precise commands are given below.

First, assume, for example, that the reference is ref.tif, and the ASP DEM is created without bundle adjustment, as:

parallel_stereo left.tif right.tif left.xml right.xml output/run
point2dem --auto-proj-center output/run-PC.tif

It is very important to distinguish the cases when the obtained DEM is the first or second argument of pc_align.

If the ASP DEM output/run-DEM.tif is aligned to the reference as:

pc_align --max-displacement 1000 ref.tif output/run-DEM.tif \
  -o align/run

then, the alignment is applied to cameras the following way:

bundle_adjust left.tif right.tif left.xml right.xml \
  --initial-transform align/run-transform.txt       \
  --apply-initial-transform-only -o ba_align/run

This should create the camera adjustments incorporating the alignment transform:

ba_align/run-left.adjust, ba_align/run-right.adjust

(see Section 16.5.12 for discussion of .adjust files).

For CSM cameras, this will also create stand-alone model state cameras with adjustments already applied to them (Section 8.11.6).

If pc_align was invoked with the two clouds in reverse order, the transform to use is:

align/run-inverse-transform.txt

The idea here is that run-transform.txt goes from the second cloud passed to pc_align to the first, hence, bundle_adjust invoked with this transform would move cameras from second cloud’s coordinate system’s to first. And vice-versa, if run-inverse-transform.txt is used, cameras from first clouds’s coordinate system would be moved to second’s.

After applying a transform this way, the cameras that are now aligned with the reference can be used to mapproject onto it, hopefully with no registration error, as:

mapproject ref.tif left.tif left_map.tif \
  --bundle-adjust-prefix ba_align/run

and in the same way for the right image. Overlaying the produced images is a very useful sanity check.

If, the initial stereo was done with cameras that already were bundle-adjusted, with output prefix initial_ba/run, so the stereo command had the option:

--bundle-adjust-prefix initial_ba/run

we need to integrate those initial adjustments with this alignment transform. To do that, again need to consider two cases, as before.

If the just-created stereo DEM is the second argument to pc_align, then run the slightly modified command:

bundle_adjust left.tif right.tif left.xml right.xml \
  --initial-transform align/run-transform.txt       \
  --input-adjustments-prefix initial_ba/run         \
  --apply-initial-transform-only -o ba_align/run

Otherwise, if the stereo DEM is the first argument to pc_align, use instead align/run-inverse-transform.txt as input to --initial-transform.

Note that this way bundle adjustment will not do any further camera refinements after the initial transform is applied.

A stereo run can be reused after the cameras have been modified as above, with the option --prev-run-prefix. Only triangulation will then be redone. Ensure the option --bundle-adjust-prefix ba_align/run is used to point to the new cameras. See Section 8.28.11 and Section 6.1.7.8.

16.54.15. Troubleshooting

Remember that filtering is applied only to the source point cloud. If you have an input cloud with a lot of noise, make sure it is being used as the source cloud.

If you are not getting good results with pc_align, something that you can try is to convert an input point cloud into a smoothed DEM. Use point2dem to do this and set --search-radius-factor if needed to fill in holes in the DEM. For some input data this can significantly improve alignment accuracy.

16.54.16. Command-line options for pc_align

--num-iterations <integer (default: 1000)>

Maximum number of iterations.

--max-displacement <float>

Maximum expected displacement (horizontal + vertical) of source points as result of alignment, in meters (after the initial guess transform is applied to the source points). Used for removing gross outliers in the source (movable) point cloud.

-o, --output-prefix <string (default: “”)>

Specify the output file prefix.

--outlier-ratio <float (default: 0.75)>

Fraction of source (movable) points considered inliers (after gross outliers further than max-displacement from reference points are removed).

--max-num-reference-points <integer (default: 10^8)>

Maximum number of (randomly picked) reference points to use.

--max-num-source-points <integer (default: 10^5)>

Maximum number of (randomly picked) source points to use (after discarding gross outliers).

--alignment-method <string (default: “point-to-plane”)>

Alignment method. Options: point-to-plane, point-to-point, similarity-point-to-plane, similarity-point-to-point (Section 16.54.3.1), nuth (Section 16.54.3.2), fgr (Section 16.54.3.3), least-squares, similarity-least-squares (Section 16.54.3.6).

--highest-accuracy

Compute with highest accuracy for point-to-plane (can be much slower).

--datum <string>

Sets the datum for CSV files. Options:

• WGS_1984

• D_MOON (1,737,400 meters)

• D_MARS (3,396,190 meters)

• MOLA (3,396,000 meters)

• NAD83

• WGS72

• NAD27

• Earth (alias for WGS_1984)

• Mars (alias for D_MARS)

• Moon (alias for D_MOON)

--semi-major-axis <float>

Explicitly set the datum semi-major axis in meters.

--semi-minor-axis <float>

Explicitly set the datum semi-minor axis in meters.

--csv-format <string>

Specify, in quotes, the format of input CSV files as a list of entries column_index:column_type (indices start from 1). Examples: '1:x 2:y 3:z' (a Cartesian coordinate system with origin at planet center is assumed, with the units being in meters), '5:lon 6:lat 7:radius_m' (longitude and latitude are in degrees, the radius is measured in meters from planet center), '3:lat 2:lon 1:height_above_datum', '1:easting 2:northing 3:height_above_datum' (for the latter need to also set --csv-srs). The height above datum is in meters. Can also use radius_km for column_type, when it is again measured from planet center.

--csv-srs <string>

The PROJ or WKT string to use to interpret the entries in input CSV files.

--compute-translation-only

Compute the transform from source to reference point cloud as a translation only (no rotation).

--save-transformed-source-points

Apply the obtained transform to the source points so they match the reference points and save them. The transformed point cloud can be gridded with point2dem (Section 16.57).

--save-inv-transformed-reference-points

Apply the inverse of the obtained transform to the reference points so they match the source points and save them.

--initial-transform <string>

The file containing the transform to be used as an initial guess. It can come from a previous run of the tool.

--initial-ned-translation <string>

Initialize the alignment transform based on a translation with this vector in the North-East-Down coordinate system around the centroid of the reference points. Specify it in quotes, separated by spaces or commas.

--initial-rotation-angle <double (default: 0.0)>

Initialize the alignment transform as the rotation with this angle (in degrees) around the axis going from the planet center to the centroid of the point cloud. If --initial-ned-translation is also specified, the translation gets applied after the rotation.

--initial-transform-from-hillshading <string>

If both input clouds are DEMs, find interest point matches among their hillshaded versions, and use them to compute an initial transform to apply to the source cloud before proceeding with alignment (Section 16.54.3.4). Specify here the type of transform, as one of: rigid (rotation + translation), translation, or similarity (rotation + translation + scale). See the options further down for tuning this. The alignment algorithm can refine the scale later if set to similarity-point-to-plane, etc.

--hillshade-options

Options to pass to the hillshade program when computing the transform from hillshading. Default: --azimuth 300 --elevation 20 --align-to-georef.

--ipfind-options

Options to pass to the ipfind program when computing the transform from hillshading. Default: --ip-per-image 1000000 --interest-operator sift --descriptor-generator sift.

--ipmatch-options

Options to pass to the ipmatch program when computing the transform from hillshading. Default: --inlier-threshold 100 --ransac-iterations 10000 --ransac-constraint similarity.

--initial-transform-ransac-params <num_iter factor (default: 10000 1.0)>

When computing an initial transform based on hillshading, use this number of RANSAC iterations and outlier factor. A smaller factor will reject more outliers.

--match-file

Compute an initial transform from the source to the reference point cloud given interest point matches from the reference to the source DEM in this file. This file can be produced manually, in stereo_gui (Section 16.54.12), or automatically, as in Section 16.54.3.4 or Section 16.54.3.5. See also --initial-transform-from-hillshading and --initial-transform-ransac-params.

--nuth-options <string (default: “”)>

Options to pass to the Nuth and Kaab algorithm. Set in quotes. See Options for Nuth and Kaab for more details.

--fgr-options <string>

Options to pass to the Fast Global Registration (FGR) algorithm. Set in quotes. Default: “div_factor: 1.4 use_absolute_scale: 0 max_corr_dist: 0.025 iteration_number: 100 tuple_scale: 0.95 tuple_max_cnt: 10000”.

--diff-rotation-error <float (default: 1e-8)>

Change in rotation amount below which the algorithm will stop (if translation error is also below bound), in degrees.

--diff-translation-error <float (default: 1e-3)>

Change in translation amount below which the algorithm will stop (if rotation error is also below bound), in meters.

--no-dem-distances

For reference point clouds that are DEMs, don’t take advantage of the fact that it is possible to interpolate into this DEM when finding the closest distance to it from a point in the source cloud (the text above has more detailed information).

--skip-shared-box-estimation

Do not estimate the shared bounding box of the two clouds. This estimation can be costly for large clouds but helps with eliminating outliers.

--threads <integer (default: 0)>

Select the number of threads to use for each process. If 0, use the value in ~/.vwrc.

--cache-size-mb <integer (default = 1024)>

Set the system cache size, in MB.

--tile-size <integer (default: 256 256)>

Image tile size used for multi-threaded processing.

--no-bigtiff

Tell GDAL to not create BigTiff files.

--tif-compress <None|LZW|Deflate|Packbits (default: LZW)>

TIFF compression method.

-v, --version

Display the version of software.

-h, --help

Display this help message.

16.54.17. Options for Nuth and Kaab

The Nuth and Kaab algorithm (Section 16.54.3.2) accepts the regular pc_align options --max-displacement, --num-iterations, --compute-translation-only, --threads.

In addition, it can be tuned via the --nuth-options argument. Its value is a string in quotes, with spaces as separators. Example:

--nuth-options "--slope-lim 0.1 40.0 --tol 0.01"

Default values will be used for any unspecified options. The options are:

--slope-lim <float float (default: 0.1 40.0)>

Minimum and maximum surface slope limits to consider (degrees).

--tol <float (default: 0.01)>

Stop when the addition to the alignment translation at given iteration has magnitude below this tolerance (meters).

--max-horizontal-offset <float>

Maximum expected horizontal translation magnitude (meters). Used to filter outliers. If not set, use the value in --max-displacement.

--max-vertical-offset <float>

Maximum expected vertical translation in meters (meters). Used to filter outliers. If not set, use the value in --max-displacement.

--num-inner-iter <integer (default: 10)>

Maximum number of iterations for the inner loop, when finding the best fit parameters for the current translation.