.. _point2las:

point2las
---------

This tool can be used to convert point clouds generated by ASP to the
public LAS format for interchange of 3-dimensional point cloud data.

If the input cloud has a datum, or the ``--datum`` option is specified,
then the output LAS file will be created in respect to this datum.
Otherwise raw :math:`x,y,z` values will be saved.

The point cloud triangulation error can be saved, if desired, in 
the LAS ``intensity`` field.

Example usage:

::

     point2las output-prefix-PC.tif -o output-prefix

This will create the file ``output-prefix.las``. If the
``--compressed`` option is used, it will write instead
``output-prefix.laz``

Outlier removal
~~~~~~~~~~~~~~~

The ``point2las`` program filters out outliers in the input point
cloud using the ray triangulation error (the fourth band in the
cloud), hence points with an error above a certain threshold are not
included in the output LAS file.

It first picks a desired number of samples from the cloud, sorts the
positive triangulation errors from the sample (the errors equal to 0
correspond to invalid points, so these are ignored), and computes some
statistical measures which are printed to the screen.  Those include
the minimum, mean, standard deviation, maximum, and the error
percentiles at 25% (Q1), 50% (median, Q2) and 75% (Q3).

Then, given the desired percentile and factor in ``--remove-outliers-params``,
it computes the error for this percentile and multiplies it by the factor.
With the default settings, this amounts to 3*Q3. 
This value is used as the cutoff threshold to remove outliers. 

If the option ``--use-tukey-outlier-removal`` is set, the outlier
cutoff is computed as Q3 + 1.5*(Q3 - Q1)
:cite:`tukey1977exploratory`. This takes precedence over the earlier approach.

Alternatively, the user can specify a custom outlier cutoff via
``--max-valid-triangulation-error``, when it will be used instead of
any of the above.

If it is desired to not remove any outliers, the percentage in 
``--remove-outliers-params`` can be set to 100.

After the LAS file is saved, the number of outliers and their
percentage from the total number of points are printed on the
screen. Generally, the outlier threshold should not be so restrictive
that more than approximately 30% of the points are eliminated.

Command-line options for point2las
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--datum <string>
    Create a geo-referenced LAS file in respect to this datum.  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)

--reference-spheroid <string>
    This is identical to the datum option.

--t_srs <proj string>
    Specify the output projection (PROJ.4 string).

--compressed
    Compress using laszip.

-o, --output-prefix <filename>
    Specify the output file prefix.

--remove-outliers-params <pct factor (default: 75.0 3.0)>
    Outlier removal based on percentage. Points with triangulation
    error larger than pct-th percentile times factor will be removed
    as outliers.

--use-tukey-outlier-removal
    Remove outliers above Q3 + 1.5*(Q3 - Q1). Takes precedence over
    the above approach.

--max-valid-triangulation-error <float (default: 0)>
    Outlier removal based on threshold. Points with triangulation error larger 
    than this, if positive (measured in meters) will be removed from the cloud.
    Takes precedence over the above options.

--triangulation-error-factor <float (default: 0)>
    If this factor is positive, save the point cloud triangulation
    error to the 2-byte LAS intensity field by storing
    min(round(factor*error), 65535). Resulting values that equal 65535
    should be treated with caution.

--num-samples-for-outlier-estimation <integer (default: 1000000)>
    Approximate number of samples to pick from the input cloud to find the 
    outlier cutoff based on triangulation error.

--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 bigtiffs.

--tif-compress <None|LZW|Deflate|Packbits (default: LZW)>
    TIFF compression method.

-v, --version
    Display the version of software.

-h, --help
    Display this help message.