Update FAQ.

doc/faq.rst

@@ -6,14 +6,17 @@ FAQ
 
 .. index:: pronounce
 
+.. |nbsp| unicode:: 0xA0
+   :trim:
+
 * How do you pronounce PDAL?
 
   The proper spelling of the project name is PDAL, in uppercase. It is
   pronounced to rhyme with "GDAL".
 
   .. it is properly pronounced like the dog though :) -- hobu
 
-|
+  |nbsp|
 
 * Why do I get the error "Couldn't create ... stage of type ..."?
 
@@ -23,7 +26,8 @@ FAQ
   be found by running ``pdal --drivers``
 
   If you've built pdal yourself, make sure you've requested to build the
-  plugin in question (set BUILD_PLUGIN_TILEDB=ON, for example, in CMakeCache.txt).
+  plugin in question (set BUILD_PLUGIN_TILEDB=ON, for example,
+  in CMakeCache.txt).
 
   If you've successfully built the plugin, a
   shared object called
@@ -41,6 +45,31 @@ FAQ
   variable ``PDAL_DRIVER_PATH`` to a list of directories that pdal should search
   for plugins.
 
+  |nbsp|
+
+* Why do I get the error ``Unable to convert scaled value ... "
+
+  This error usually occurs when writing LAS files, but can occur with other
+  formats.
+
+  Simply, the output format you've chosen doesn't support values as large
+  (or small) as those that you're trying to write.  For example. if the
+  output format specifies 32-bit signed integers, attempting to write a
+  value larger than 2,147,483,647 will cause this error, as 2,147,483,647
+  is the largest 32-bit signed integer.
+
+  The LAS format always stores X, Y and Z values as 32-bit integers.
+  You can specify a scale factor to be applied to those values in order
+  to change their magnitude, but their precision is limited to 32 bits.
+  If the value
+  you're attempting to write, when divided by the scale factor you've
+  specified, is larger than 2,147,483,647, you will get this error.
+  For example, if you attempt to write the value 6 with a scale factor
+  of .000000001, you'll get this error, as 6 / .000000001 is 6,000,000,000,
+  which is larger than the maximum integer value.
+
+  |nbsp|
+
 * Why am I using 100GB of memory when trying to process a 10GB LAZ file?
 
   If you're performing an operation that is using
@@ -53,7 +82,7 @@ FAQ
   :ref:`stream mode <processing_modes>` to
   limit memory consumption when possible.
 
-|
+  |nbsp|
 
 * What is PDAL's relationship to PCL?
 
@@ -66,6 +95,8 @@ FAQ
 
         :ref:`about_pcl` describes PDAL and PCL's relationship.
 
+  |nbsp|
+
 * What is PDAL's relationship to libLAS?
 
   The idea behind libLAS was limited to LIDAR data and basic
@@ -76,9 +107,7 @@ FAQ
   talked more about this history in a `GeoHipster interview`_ in
   2018.
 
-.. _`GeoHipster interview`: http://geohipster.com/2018/03/05/howard-butler-like-good-song-open-source-software-chance-immortal/
-
-|
+  |nbsp|
 
 * Are there any command line tools in PDAL similar to LAStools?
 
@@ -92,20 +121,25 @@ FAQ
         :ref:`apps` describes application operations you can
         achieve with PDAL.
 
+  |nbsp|
+
 * Is there any compatibility with libLAS's LAS Utility Applications or LAStools?
 
   No. The the command line interface was developed from scratch with
   focus on usability and readability. You will find that the ``pdal``
   command has several well-organized subcommands such as ``info``
   or ``translate`` (see :ref:`apps`).
 
+  |nbsp|
+
 * I get GeoTIFF errors. What can I do about them?
 
   ::
 
-    (readers.las Error) Geotiff directory contains key 0 with short entry and more than one value.
+    (readers.las Error) Geotiff directory contains key 0 with short entry
+    and more than one value.
 
-  If :ref:`readers.las` is outputting error messages about GeoTIFF, this means
+  If :ref:`readers.las` is emitting error messages about GeoTIFF, this means
   the keys that were written into your file were incorrect or at least not
   readable by `libgeotiff`_. Rewrite the file using PDAL to fix the issue:
 
@@ -114,3 +148,5 @@ FAQ
     pdal translate badfile.las goodfile.las --writers.las.forward=all
 
 .. _`libgeotiff`: https://trac.osgeo.org/geotif
+.. _`GeoHipster interview`: http://geohipster.com/2018/03/05/howard-butler-like-good-song-open-source-software-chance-immortal/
+