diff --git a/.gitignore b/.gitignore index 6a390200e5..32cff87d32 100644 --- a/.gitignore +++ b/.gitignore @@ -140,3 +140,8 @@ test/data/qfit/little-endian-conversion.xml test/data/qfit/pipeline.xml test/data/qfit/reader.xml test/data/sbet/pipeline.xml + +python/*.egg* +python/build/* +python/pdal/libpdalpython.so +python/pdal/libpdalpython.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 4ebbb30e4b..92a4e96da7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -28,13 +28,14 @@ mark_as_advanced(CMAKE_VERBOSE_MAKEFILE) # the next line is the ONLY place in the entire pdal system where # the version info is hard-coded -set(PDAL_VERSION_STRING "1.0.0.b1" CACHE STRING "PDAL version" FORCE) +set(PDAL_VERSION_STRING "1.0.1" CACHE STRING "PDAL version" FORCE) DISSECT_VERSION() GET_OS_INFO() SET_INSTALL_DIRS() -SET(PDAL_LIB_SOVERSION "0.0.0") +set(PDAL_API_VERSION "1") +set(PDAL_BUILD_VERSION "1.0.0") # Name of C++ library @@ -47,14 +48,16 @@ SET(PDAL_LIB_SOVERSION "0.0.0") # On OSX we reexport the symbols from libpdal_util.dylib into libpdalcpp.dylib # See src/CMakeLists.txt for the rest of the magic. # -if (APPLE OR WINDOWS) +if (APPLE OR WIN32) set(PDAL_LIB_NAME pdalcpp) set(PDAL_BASE_LIB_NAME pdalcpp) set(PDAL_UTIL_LIB_NAME pdal_util) + set(PDAL_PLANG_LIB_NAME pdal_plang) else() set(PDAL_LIB_NAME pdalcpp) set(PDAL_BASE_LIB_NAME pdal_base) set(PDAL_UTIL_LIB_NAME pdal_util) + set(PDAL_PLANG_LIB_NAME pdal_plang) endif() set(CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE ON) @@ -264,6 +267,9 @@ add_subdirectory(filters) add_subdirectory(kernels) add_subdirectory(src) add_subdirectory(tools) +if (BUILD_PLUGIN_PYTHON) + add_subdirectory(src/plang) +endif() if(WITH_TESTS) # This is fixed in trunk @@ -335,6 +341,7 @@ list(APPEND CPACK_SOURCE_IGNORE_FILES "Testing") list(APPEND CPACK_SOURCE_IGNORE_FILES "PDAL.build/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/bin/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/lib/") +list(APPEND CPACK_SOURCE_IGNORE_FILES "/build/") list(APPEND CPACK_SOURCE_IGNORE_FILES "Makefile") list(APPEND CPACK_SOURCE_IGNORE_FILES "CMakeFiles") list(APPEND CPACK_SOURCE_IGNORE_FILES "CTestTestfile.cmake") @@ -342,7 +349,6 @@ list(APPEND CPACK_SOURCE_IGNORE_FILES "/test/data/local/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/doc/doxygen/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/doc/build/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/doc/presentations/") -list(APPEND CPACK_SOURCE_IGNORE_FILES "/scripts/") list(APPEND CPACK_SOURCE_IGNORE_FILES "/cmake/examples/") include(CPack) diff --git a/HOWTORELEASE.txt b/HOWTORELEASE.txt new file mode 100644 index 0000000000..4f283c9470 --- /dev/null +++ b/HOWTORELEASE.txt @@ -0,0 +1,82 @@ + +Steps for Making a PDAL Release +============================================================================== + +:Author: Howard Butler +:Contact: howard@hobu.co +:Date: 09/11/2015 + +This document describes the process for releasing a new version of PDAL. + +General Notes +------------------------------------------------------------------------------ + +Release Process + +1) Increment Version Numbers + + - CMakeLists.txt + * set(PDAL_VERSION_STRING "1.0.0" CACHE STRING "PDAL version") + * DISSECT_VERSION() CMake macro will break version down into + PDAL_VERSION_MAJOR, PDAL_VERSION_MINOR, PDAL_VERSION_PATCH, + and PDAL_CANDIDATE_VERSION strings. + + - Update SO versioning + set(PDAL_API_VERSION "1") + set(PDAL_BUILD_VERSION "1.0.0") + * https://github.com/libspatialindex/libspatialindex/pull/44#issuecomment-57088783 + +2) Update README to include any relevant info about the release that + might have changed. + +3) Update ChangeLog with git2cl + + * git2cl . > ChangeLog + +4) Build and run the tests. Really. + + :: + + ctest -V + +5) Clone a new tree and issue cmake. The package_source CMake target is + aggressive about scooping up every file in the tree to include in the package. + It does ok with CMake-specific stuff, but any other cruft in the tree is + likely to get dumped into the package. + + :: + + git clone git://github.com/PDAL/PDAL.git pdal2 + cmake . + +6) Make the source distribution. If you are doing a release candidate + add an RC tag to the invocation. + + :: + + ./package.sh + ./package.sh RC1 + + + package.sh will rename the source files if necessary for the release + candidate tag and create .md5 sum files. This script only works on + linux and windows. + +7) Update docs/download.txt to point at the location of the new release + +8) Upload the new release to download.osgeo.org:/osgeo/download/pdal + + :: + + scp PDAL-* hobu@download.osgeo.org:/osgeo/download/pdal + +9) Tag the release. Use the ``-f`` switch if you are retagging because you + missed something. + + :: + git tag 1.0.0 + git push --tags + + +10) Write the release notes. Email PDAL mailing list with notice about release + diff --git a/apps/CMakeLists.txt b/apps/CMakeLists.txt index 48a60bcc89..79d2b52de7 100644 --- a/apps/CMakeLists.txt +++ b/apps/CMakeLists.txt @@ -67,26 +67,44 @@ else(APPLE AND PDAL_BUNDLE) RUNTIME DESTINATION ${PDAL_BIN_INSTALL_DIR}) endif(APPLE AND PDAL_BUNDLE) -if(UNIX) +if(UNIX OR APPLE) - get_directory_property(PDAL_DEFINITIONS DIRECTORY ${PDAL_SOURCE_DIR}/../src COMPILE_DEFINITIONS) + set(PKGCONFIG_LIBRARY_DEFINITIONS "") + set(PDAL_INCLUDE_DEFINITIONS "-I${CMAKE_INSTALL_PREFIX}/include -I${Boost_INCLUDE_DIR} -I${GDAL_INCLUDE_DIR}") + set(PKGCONFIG_LIBRARY_DEFINITIONS "${PKGCONFIG_LIBRARY_DEFINITIONS} gdal") - set(PDAL_CONFIG_DEFINITIONS "") - foreach(definition ${PDAL_DEFINITIONS}) - set(PDAL_CONFIG_DEFINITIONS "${PDAL_CONFIG_DEFINITIONS} -D${definition}") - endforeach() + if(LIBXML2_FOUND) + set(PKGCONFIG_LIBRARY_DEFINITIONS "${PKGCONFIG_LIBRARY_DEFINITIONS} libxml-2.0") + set(PDAL_INCLUDE_DEFINITIONS "${PDAL_INCLUDE_DEFINITIONS} -I${LIBXML2_INCLUDE_DIR}") + endif() - # Autoconf compatibility variables to use the same script source. - set(prefix ${CMAKE_INSTALL_PREFIX}) - set(exec_prefix ${CMAKE_INSTALL_PREFIX}/bin) - set(libdir ${CMAKE_INSTALL_PREFIX}/lib) + if (GEOS_FOUND) + set(PKGCONFIG_LIBRARY_DEFINITIONS "${PKGCONFIG_LIBRARY_DEFINITIONS} geos") + set(PDAL_INCLUDE_DEFINITIONS "${PDAL_INCLUDE_DEFINITIONS} -I${GEOS_INCLUDE_DIR}") + endif() + + if (LASZIP_FOUND) + set(PDAL_INCLUDE_DEFINITIONS "${PDAL_INCLUDE_DEFINITIONS} -I${LASZIP_INCLUDE_DIR}") + endif() + + file(MAKE_DIRECTORY "${PDAL_OUTPUT_LIB_DIR}/pkgconfig/") + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/pdal.pc.in + ${CMAKE_CURRENT_BINARY_DIR}/pdal.pc @ONLY) + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/pdal.pc + DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/pkgconfig/" + PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/pdal-config.in - ${CMAKE_CURRENT_BINARY_DIR}/pdal-config @ONLY) - install(FILES ${CMAKE_CURRENT_BINARY_DIR}/pdal-config - DESTINATION "${CMAKE_INSTALL_PREFIX}/${PDAL_BIN_INSTALL_DIR}" - PERMISSIONS - OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) + # Autoconf compatibility variables to use the same script source. + configure_file("${CMAKE_CURRENT_SOURCE_DIR}/pdal-config.in" + "${CMAKE_CURRENT_SOURCE_DIR}/pdal-config" @ONLY) + + file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/pdal-config" + DESTINATION "${PDAL_OUTPUT_BIN_DIR}/" + FILE_PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) + install(PROGRAMS "${PDAL_OUTPUT_BIN_DIR}/pdal-config" + DESTINATION "${CMAKE_INSTALL_PREFIX}/bin" + PERMISSIONS + OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) endif() diff --git a/apps/pdal-config.in b/apps/pdal-config.in index d4ee82caf7..d328eef130 100644 --- a/apps/pdal-config.in +++ b/apps/pdal-config.in @@ -1,7 +1,7 @@ #!/bin/sh -prefix=@prefix@ -exec_prefix=@exec_prefix@ -libdir=@libdir@ +prefix=@CMAKE_INSTALL_PREFIX@ +exec_prefix=@CMAKE_INSTALL_PREFIX@/bin +libdir=@CMAKE_INSTALL_PREFIX@/lib usage() @@ -9,11 +9,12 @@ usage() cat <&2 fi -case $1 in - --libs) - echo $LIBS +case $1 in + --libs) + echo -L@CMAKE_INSTALL_PREFIX@/lib -lpdalcpp + ;; + + --plugin-dir) + echo @PDAL_PLUGIN_INSTALL_PATH@ ;; --prefix) @@ -41,7 +46,7 @@ case $1 in ;; --includes) - echo ${INCLUDES} + echo @PDAL_INCLUDE_DEFINITIONS@ ;; --cflags) @@ -49,9 +54,9 @@ case $1 in ;; --cxxflags) - echo @CMAKE_CXX_FLAGS@ + echo @CMAKE_CXX_FLAGS@ -std=c++11 ;; - + --version) echo @PDAL_VERSION_STRING@ ;; diff --git a/apps/pdal.pc.in b/apps/pdal.pc.in new file mode 100644 index 0000000000..c9cb7c4bb5 --- /dev/null +++ b/apps/pdal.pc.in @@ -0,0 +1,12 @@ +prefix=@CMAKE_INSTALL_PREFIX@ +exec_prefix=@CMAKE_INSTALL_PREFIX@/bin +libdir=@CMAKE_INSTALL_PREFIX@/lib +includedir=@CMAKE_INSTALL_PREFIX@/include + +Name: PDAL +Description: Point Data Abstraction Library +Requires: @PKGCONFIG_LIBRARY_DEFINITIONS@ +Version: @PDAL_VERSION_STRING@ +Libs: -L${libdir} -l@PDAL_LIB_NAME@ +Cflags: -I${includedir}/pdal @PDAL_CONFIG_DEFINITIONS@ + diff --git a/cmake/examples/hobu-config.sh b/cmake/examples/hobu-config.sh index 9a1a6b80b7..a33f26fb03 100755 --- a/cmake/examples/hobu-config.sh +++ b/cmake/examples/hobu-config.sh @@ -64,3 +64,10 @@ CC=$CC CXX=$CXX cmake -G "$CONFIG" \ -DPGPOINTCLOUD_TEST_DB_HOST="localhost" +# -DPYTHON_EXECUTABLE=/usr/local/bin/python \ +# -DPYTHON_LIBRARY=/usr/local/Cellar/python/2.7.10_2/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib \ +# -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python/2.7.10_2/Frameworks/Python.framework/Versions/2.7/include/python2.7/ \ + +# -DPYTHON_EXECUTABLE=/usr/local/bin/python3 \ +# -DPYTHON_LIBRARY=/usr/local/Cellar/python3/3.4.2_1/Frameworks/Python.framework/Versions/3.4/lib/libpython3.4.dylib \ +# -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python3/3.4.2_1/Frameworks/Python.framework/Versions/3.4/include/python3.4m/ \ diff --git a/doc/apps.rst b/doc/apps.rst index 81a5377190..99873a5d23 100644 --- a/doc/apps.rst +++ b/doc/apps.rst @@ -8,21 +8,22 @@ PDAL Applications :Contact: howard at hobu.co :Date: 6/1/2015 -PDAL contains consists of a single application, called *pdal*. The `pdal` +PDAL contains consists of a single application, called ``pdal``. The ```pdal`` application currently has the following subcommands: * :ref:`delta ` +* :ref:`diff ` * :ref:`ground ` * :ref:`info ` * :ref:`pcl ` * :ref:`pipeline ` * :ref:`random ` -* :ref:`view ` * :ref:`split ` * :ref:`tindex ` * :ref:`translate ` +* :ref:`view ` -Applications are run by invoking the *pdal* application along with the +Applications are run by invoking the ``pdal`` application along with the command name: :: @@ -31,9 +32,9 @@ command name: $ pdal translate input.las output.las $ pdal pipeline --stdin < myxml.xml -Help for each command can be retrieved via the ``--help`` switch. -The ``--drivers`` and ``--options`` switches can tell you more about -particular drivers and their options: +Help for each command can be retrieved via the ``--help`` switch. The +``--drivers`` and ``--options`` switches can tell you more about particular +drivers and their options: :: @@ -42,21 +43,20 @@ particular drivers and their options: $ pdal pipeline --options writers.las Additional driver-specific options may be specified by using a -namespace-prefixed option name. For example, it is possible to -set the LAS day of year at translation time with the following -option: +namespace-prefixed option name. For example, it is possible to set the LAS day +of year at translation time with the following option: :: $ pdal translate \ - --writers.las.creation_doy="42" \ - input.las - output.las + --writers.las.creation_doy="42" \ + input.las \ + output.las .. note:: - Driver specific options can be identified using the - ``pdal info --options`` invocation. + Driver specific options can be identified using the ``pdal info --options`` + invocation. .. _delta_command: @@ -64,7 +64,7 @@ option: delta command ------------------------------------------------------------------------------ -The *delta* command is used to select a nearest point from a candidate file +The ``delta`` command is used to select a nearest point from a candidate file for each point in the source file. If the ``--2d`` option is used, the query only happens in XY coordinate space. @@ -72,21 +72,22 @@ query only happens in XY coordinate space. $ pdal delta [output] - Standard out is used if no output file is specified. +Standard out is used if no output file is specified. :: - --source arg Non-positional option for specifying source filename - --candidate arg Non-positional option for specifying candidate filename - --output arg Non-positional option for specifying output filename [/dev/stdout] - --2d only 2D comparisons/indexing + --source arg Non-positional option for specifying source filename + --candidate arg Non-positional option for specifying candidate filename + --output arg Non-positional option for specifying output filename [/dev/stdout] + --2d only 2D comparisons/indexing Example 1: ^^^^^^^^^^^^^ :: - $ pdal delta ../../test/data/las/1.2-with-color.las ../../test/data/las/1.2-with-color.las + $ pdal delta ../../test/data/las/1.2-with-color.las \ + ../../test/data/las/1.2-with-color.las -------------------------------------------------------------------------------- Delta summary for source: '../../test/data/las/1.2-with-color.las' @@ -101,14 +102,13 @@ Example 1: Mean 0.0000 0.0000 0.0000 ----------- --------------- --------------- -------------- - - Example 2: ^^^^^^^^^^ :: - $ ./bin/pdal delta test/data/1.2-with-color.las test/data/1.2-with-color.las --detail + $ pdal delta test/data/1.2-with-color.las \ + test/data/1.2-with-color.las --detail "ID","DeltaX","DeltaY","DeltaZ" 0,0.00,0.00,0.00 1,0.00,0.00,0.00 @@ -119,19 +119,18 @@ Example 2: .... - .. _diff_command: diff command ------------------------------------------------------------------------------ -The *diff* command is used for executing a simple contextual difference +The ``diff`` command is used for executing a simple contextual difference between two sources. :: $ pdal diff - + :: --source arg Non-positional option for specifying filename of source file. @@ -155,20 +154,18 @@ The command checks for the equivalence of the following items: ground command ------------------------------------------------------------------------------ -The *ground* command is used to segment the input point cloud into ground +The ``ground`` command is used to segment the input point cloud into ground versus non-ground returns. The output is a point cloud containing only ground -returns. The *ground* command invokes `Point Cloud Library +returns. The ``ground`` command invokes `Point Cloud Library `_'s `ProgressiveMorphologicalFilter`_. -.. _`ProgressiveMorphologicalFilter`: http://pointclouds.org/documentation/tutorials/progressive_morphological_filtering.php#progressive-morphological-filtering. - .. note:: - The *ground* command is only available when PDAL is linked with PCL. + The ``ground`` command is only available when PDAL is linked with PCL. :: - pdal ground + $ pdal ground :: @@ -195,12 +192,12 @@ Dumps information about a point cloud file, such as: * coordinate reference system * additional metadata * summary statistics about the points -* the plain text format should be reStructured text if possible to allow - a user to retransform the output into whatever they want with ease +* the plain text format should be reStructured text if possible to allow a user + to retransform the output into whatever they want with ease :: - pdal info + $ pdal info :: @@ -225,14 +222,15 @@ Dumps information about a point cloud file, such as: names. --metadata Dump the metadata associated with the input file. -If no options are provided, --statistics is assumed. +If no options are provided, ``--stats`` is assumed. Example 1: ^^^^^^^^^^^^ :: - $ pdal info test/data/las/1.2-with-color.las --query="636601.87, 849018.59, 425.10" + $ pdal info test/data/las/1.2-with-color.las \ + --query="636601.87, 849018.59, 425.10" { "0": { @@ -333,16 +331,16 @@ Example 2: pcl command ------------------------------------------------------------------------------ -The *pcl* command is used to invoke a PCL JSON pipeline. See :ref:`pcl_block_tutorial` -for more information. +The ``pcl`` command is used to invoke a PCL JSON pipeline. See +:ref:`pcl_block_tutorial` for more information. .. note:: - The *pcl* command is only available when PDAL is linked with PCL. + The ``pcl`` command is only available when PDAL is linked with PCL. :: - pdal pcl + $ pdal pcl :: @@ -358,12 +356,12 @@ for more information. pipeline command ------------------------------------------------------------------------------ -The *pipeline* command is used to execute :ref:`pipeline` XML. See +The ``pipeline`` command is used to execute :ref:`pipeline` XML. See :ref:`reading` or :ref:`pipeline` for more information. :: - pdal pipeline + $ pdal pipeline :: @@ -376,16 +374,16 @@ The *pipeline* command is used to execute :ref:`pipeline` XML. See .. note:: - The `pipeline` command can accept option substitutions, but they + The ``pipeline`` command can accept option substitutions, but they do not replace existing options that are specified in the input XML pipeline. For example, to set the output and input LAS files for a pipeline that does a translation, construct XML that does not contain - `filename` for reader and writer and issue the command with the + ``filename`` for reader and writer and issue the command with the following arguments: :: - pdal pipeline -i translate.xml --writers.las.filename=output.laz \ + $ pdal pipeline -i translate.xml --writers.las.filename=output.laz \ --readers.las.filename=input.las @@ -394,8 +392,8 @@ The *pipeline* command is used to execute :ref:`pipeline` XML. See random command ------------------------------------------------------------------------------ -The *random* command is used to create a random point cloud. It uses -:ref:`readers.faux` to create a point cloud containing *count* points +The ``random`` command is used to create a random point cloud. It uses +:ref:`readers.faux` to create a point cloud containing ``count`` points drawn randomly from either a uniform or normal distribution. For the uniform distribution, the bounds can be specified (they default to a unit cube). For the normal distribution, the mean and standard deviation can both be set for @@ -403,7 +401,7 @@ each of the x, y, and z dimensions. :: - pdal random + $ pdal random :: @@ -421,124 +419,18 @@ each of the x, y, and z dimensions. --distribution arg Distribution type (uniform or normal) [uniform] -.. _translate_command: - -translate command ------------------------------------------------------------------------------- - -The *translate* command is used for simple conversion of files based on their -file extensions. Use the :ref:`pipeline_command` for more significant -translation operations. - -:: - - pdal translate - -:: - - --input [-i] arg Non-positional argument to specify input file name. - --output [-o] arg Non-positional argument to specify output file name. - --compress arg Compress output data if supported by output format. [false] - --a_srs arg Assign input coordinate system. - --t_srs arg Transform to output coordinate system. - --bounds arg Limit output to points inside the specified box. - --bounds "([xmin,xmax],[ymin,ymax])" - --polygon arg Limit output to point inside the specified polygon (specified as - well-known text). - --d_step arg Step value to be passed to decimation filter. [1] - --d_offset arg Offset value to be passed to decimation filter. [0] - --d_leaf_size arg Leaf size to be bassed to decimation filter. [1] - --d_method arg Decimation filter method (RankOrder|VoxelGrid). [RankOrder] - --d_limit arg Limit to be passed to decimation filter. [0] - -The translate command can be augmented by specifying full-path options at the -command line invocation. For example, the following invocation will translate -`1.2-with-color.las` to `output.laz` while doing the following: - -* Setting the creation day of year to 42 -* Setting the creation year to 2014 -* Setting the LAS point format to 1 -* Cropping the file with the given polygon - -:: - - ./bin/pdal translate \ - --writers.las.creation_doy="42" \ - --writers.las.creation_year="2014" \ - --writers.las.format="1" \ - --filters.crop.polygon="POLYGON ((636889.412951239268295 851528.512293258565478 422.7001953125,636899.14233423944097 851475.000686757150106 422.4697265625,636899.14233423944097 851475.000686757150106 422.4697265625,636928.33048324030824 851494.459452757611871 422.5400390625,636928.33048324030824 851494.459452757611871 422.5400390625,636928.33048324030824 851494.459452757611871 422.5400390625,636976.977398241520859 851513.918218758190051 424.150390625,636976.977398241520859 851513.918218758190051 424.150390625,637069.406536744092591 851475.000686757150106 438.7099609375,637132.647526245797053 851445.812537756282836 425.9501953125,637132.647526245797053 851445.812537756282836 425.9501953125,637336.964569251285866 851411.759697255445644 425.8203125,637336.964569251285866 851411.759697255445644 425.8203125,637473.175931254867464 851158.795739248627797 435.6298828125,637589.928527257987298 850711.244121236610226 420.509765625,637244.535430748714134 850511.791769731207751 420.7998046875,636758.066280735656619 850667.461897735483944 434.609375,636539.155163229792379 851056.63721774588339 422.6396484375,636889.412951239268295 851528.512293258565478 422.7001953125))" \ - ./test/data/1.2-with-color.las \ - output.laz - -.. _view_command: - -view command ------------------------------------------------------------------------------- - -The *view* command can be used to visualize a point cloud using the -PCLVisualizer. The command takes a single argument, the input file name. - -.. note:: - - The *view* command is only available when PDAL is linked with PCL. - -:: - - $ pdal view - -Once the data has been loaded into the viewer, press h or H to display the -help. - -:: - - | Help: - ------- - p, P : switch to a point-based representation - w, W : switch to a wireframe-based representation (where available) - s, S : switch to a surface-based representation (where available) - - j, J : take a .PNG snapshot of the current window view - c, C : display current camera/window parameters - f, F : fly to point mode - - e, E : exit the interactor - q, Q : stop and call VTK's TerminateApp - - +/- : increment/decrement overall point size - +/- [+ ALT] : zoom in/out - - g, G : display scale grid (on/off) - u, U : display lookup table (on/off) - - o, O : switch between perspective/parallel projection (default = perspective) - r, R [+ ALT] : reset camera [to viewpoint = {0, 0, 0} -> center_{x, y, z}] - CTRL + s, S : save camera parameters - CTRL + r, R : restore camera parameters - - ALT + s, S : turn stereo mode on/off - ALT + f, F : switch between maximized window mode and original size - - l, L : list all available geometric and color handlers for the current actor map - ALT + 0..9 [+ CTRL] : switch between different geometric handlers (where available) - 0..9 [+ CTRL] : switch between different color handlers (where available) - - SHIFT + left click : select a point (start with -use_point_picking) - - x, X : toggle rubber band selection mode for left mouse button - - .. _split_command: split command ------------------------------------------------------------------------------ -The *split* command will create multiple output files from a single -input file. The command takes an input file name and an output filename -(used as a template) or output directory specification. +The ``split`` command will create multiple output files from a single input +file. The command takes an input file name and an output filename (used as a +template) or output directory specification. :: - pdal split + $ pdal split :: @@ -547,17 +439,16 @@ input file. The command takes an input file name and an output filename --length arg Edge length for splitter cells. See :ref:`filters.splitter`. --capacity arg Point capacity for chipper cells. See :ref:`filters.chipper`. -If neither the length nor capacity arguments are specified, an implcit argument of -capacity with a value of 100000 is added. +If neither the ``--length`` nor ``--capacity`` arguments are specified, an +implcit argument of capacity with a value of 100000 is added. The output argument is a template. If the output argument is, for example, -'file.ext', the output files created are 'file_#.ext' where # is a number +``file.ext``, the output files created are ``file_#.ext`` where # is a number starting at one and incrementing for each file created. If the output argument ends in a path separator, it is assumed to be a directory and the input argument is appended to create the output template. -The split command never creates directories. Directories must pre-exist. - +The ``split`` command never creates directories. Directories must pre-exist. Example 1: ^^^^^^^^^^^ @@ -566,8 +457,8 @@ Example 1: $ pdal split --capacity 100000 infile.laz outfile.bpf -This command takes the points from the input file 'infile.laz' and creates -output files 'outfile_1.bpf', 'outfile_2.bpf', ... where each output file +This command takes the points from the input file ``infile.laz`` and creates +output files ``outfile_1.bpf``, ``outfile_2.bpf``, ... where each output file contains no more than 100000 points. @@ -576,18 +467,17 @@ contains no more than 100000 points. tindex command ------------------------------------------------------------------------------ -The *tindex* command is used to create a `GDAL`_-style tile index for +The ``tindex`` command is used to create a `GDAL`_-style tile index for PDAL-readable point cloud types (see `gdaltindex`_). .. note:: - The *tindex* command is only available when PDAL is linked with `GDAL`_. + The ``tindex`` command is only available when PDAL is linked with `GDAL`_. -The *tindex* command has two modes. The first mode creates a spatial index +The ``tindex`` command has two modes. The first mode creates a spatial index file for a set of point cloud files. The second mode creates a point cloud file that is the result of merging the points from files referred to in a -spatial index file that meet some criteria (usually a geographic region -filter). +spatial index file that meet some criteria (usually a geographic region filter). tindex Creation Mode ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -596,17 +486,17 @@ tindex Creation Mode $ pdal tindex -This command will index the files referred to by 'filespec' and place the -result in 'tindex'. The 'tindex' is a vector file or database that -can be handled by `OGR `_. The type of -the index file can be specified by specifying the OGR code for the format -using the *--driver* option. If no driver is specified, the format defaults -to "ESRI Shapefile". +This command will index the files referred to by ``filespec`` and place the +result in ``tindex``. The ``tindex`` is a vector file or database that can be +handled by `OGR `_. The type of the index +file can be specified by specifying the OGR code for the format using the +``--driver`` option. If no driver is specified, the format defaults to "ESRI +Shapefile". -In vector file-speak, each file specified by 'filespec' is stored as a feature -in a layer in the index file. The filespec is a -`glob pattern '_. and -normally needs to be quoted to prevent shell expansion of wildcard characters. +In vector file-speak, each file specified by ``filespec`` is stored as a feature +in a layer in the index file. The ``filespec`` is a `glob pattern +'_. and normally needs to be +quoted to prevent shell expansion of wildcard characters. :: @@ -632,10 +522,10 @@ tindex Merge Mode $ pdal tindex --merge -This command will read the index file 'tindex' and merge the points in the -files listed index file that pass any filter that might be specified, -writing the output to the point cloud file specified in 'filespec'. The type -of the output file is determined automatically from the filename extension. +This command will read the index file ``tindex`` and merge the points in the +files listed index file that pass any filter that might be specified, writing +the output to the point cloud file specified in ``filespec``. The type of the +output file is determined automatically from the filename extension. :: @@ -652,12 +542,13 @@ of the output file is determined automatically from the filename extension. Example 1: ^^^^^^^^^^^ -Find all LAS files via `find`, send that file list via STDIN to `pdal tindex`, -and write a `SQLite` tile index file with a layer named `pdal`: +Find all LAS files via ``find``, send that file list via STDIN to +``pdal tindex``, and write a SQLite tile index file with a layer named ``pdal``: :: - find las/ -iname "*.las" | pdal tindex index.sqlite -f "SQLite" --stdin --lyr_name pdal + $ find las/ -iname "*.las" | pdal tindex index.sqlite -f "SQLite" \ + --stdin --lyr_name pdal Example 2: ^^^^^^^^^^^ @@ -667,8 +558,141 @@ write out an `SQLite`_ file. :: - pdal tindex index.sqlite "*.las" -f "SQLite" --lyr_name "pdal" --t_srs "EPSG:4326" + $ pdal tindex index.sqlite "*.las" -f "SQLite" --lyr_name "pdal" \ + --t_srs "EPSG:4326" + + +.. _translate_command: + +translate command +------------------------------------------------------------------------------ + +The ``translate`` command can be used for simple conversion of files based on +their file extensions. It can also be used for constructing pipelines directly +from the command-line. + +:: + + $ pdal translate + +:: + + -i [ --input ] arg input file name + -o [ --output ] arg output file name + -p [ --pipeline ] arg pipeline output + -r [ --reader ] arg reader type + -f [ --filter ] arg filter type + -w [ --writer ] arg writer type + +The ``--input`` and ``--output`` file names are required options. + +The ``--pipeline`` file name is optional. If given, the pipeline constructed +from the command-line arguments will be written to disk for reuse in the +:ref:`pipeline_command`. + +The ``--filter`` flag is optional. It is used to specify the driver used to +filter the data. ``--filter`` accepts multiple arguments if provided, thus +constructing a multi-stage filtering operation. + +If no ``--reader`` or ``--writer`` type are given, PDAL will attempt to infer +the correct drivers from the input and output file name extensions respectively. + +Example 1: +^^^^^^^^^^^ + +The ``translate`` command can be augmented by specifying full-path options at +the command-line invocation. For example, the following invocation will +translate ``1.2-with-color.las`` to ``output.laz`` while doing the following: + +* Setting the creation day of year to 42 +* Setting the creation year to 2014 +* Setting the LAS point format to 1 +* Cropping the file with the given polygon + +:: + + $ pdal translate \ + --writers.las.creation_doy="42" \ + --writers.las.creation_year="2014" \ + --writers.las.format="1" \ + --filters.crop.polygon="POLYGON ((636889.412951239268295 851528.512293258565478 422.7001953125,636899.14233423944097 851475.000686757150106 422.4697265625,636899.14233423944097 851475.000686757150106 422.4697265625,636928.33048324030824 851494.459452757611871 422.5400390625,636928.33048324030824 851494.459452757611871 422.5400390625,636928.33048324030824 851494.459452757611871 422.5400390625,636976.977398241520859 851513.918218758190051 424.150390625,636976.977398241520859 851513.918218758190051 424.150390625,637069.406536744092591 851475.000686757150106 438.7099609375,637132.647526245797053 851445.812537756282836 425.9501953125,637132.647526245797053 851445.812537756282836 425.9501953125,637336.964569251285866 851411.759697255445644 425.8203125,637336.964569251285866 851411.759697255445644 425.8203125,637473.175931254867464 851158.795739248627797 435.6298828125,637589.928527257987298 850711.244121236610226 420.509765625,637244.535430748714134 850511.791769731207751 420.7998046875,636758.066280735656619 850667.461897735483944 434.609375,636539.155163229792379 851056.63721774588339 422.6396484375,636889.412951239268295 851528.512293258565478 422.7001953125))" \ + ./test/data/1.2-with-color.las \ + output.laz + +Example 2: +^^^^^^^^^^^ + +Given these tools, we can now construct a custom pipeline on-the-fly. The +example below uses a simple LAS reader and writer, but stages a PCL-based +voxel grid filter, followed by the PCL-based ground filter. We can even set +stage-specific parameters as shown. + +:: + + $ pdal translate input.las output.las \ + --filter filters.pclblock filters.ground \ + --filters.pclblock.json="{\"pipeline\":{\"filters\":[{\"name\":\"VoxelGrid\"}]}}" \ + --filters.ground.approximate=true --filters.ground.extract=true + + +.. _view_command: + +view command +------------------------------------------------------------------------------ + +The ``view`` command can be used to visualize a point cloud using the +PCLVisualizer. The command takes a single argument, the input file name. + +.. note:: + + The ``view`` command is only available when PDAL is linked with PCL. + +:: + + $ pdal view + +Once the data has been loaded into the viewer, press h or H to display the +help. + +:: + + | Help: + ------- + p, P : switch to a point-based representation + w, W : switch to a wireframe-based representation (where available) + s, S : switch to a surface-based representation (where available) + + j, J : take a .PNG snapshot of the current window view + c, C : display current camera/window parameters + f, F : fly to point mode + + e, E : exit the interactor + q, Q : stop and call VTK's TerminateApp + + +/- : increment/decrement overall point size + +/- [+ ALT] : zoom in/out + + g, G : display scale grid (on/off) + u, U : display lookup table (on/off) + + o, O : switch between perspective/parallel projection (default = perspective) + r, R [+ ALT] : reset camera [to viewpoint = {0, 0, 0} -> center_{x, y, z}] + CTRL + s, S : save camera parameters + CTRL + r, R : restore camera parameters + + ALT + s, S : turn stereo mode on/off + ALT + f, F : switch between maximized window mode and original size + + l, L : list all available geometric and color handlers for the current actor map + ALT + 0..9 [+ CTRL] : switch between different geometric handlers (where available) + 0..9 [+ CTRL] : switch between different color handlers (where available) + + SHIFT + left click : select a point (start with -use_point_picking) + + x, X : toggle rubber band selection mode for left mouse button + .. _`SQLite`: http://www.sqlite.org .. _`gdaltindex`: http://www.gdal.org/gdaltindex.html .. _`GDAL`: http://www.gdal.org +.. _`ProgressiveMorphologicalFilter`: http://pointclouds.org/documentation/tutorials/progressive_morphological_filtering.php#progressive-morphological-filtering. diff --git a/doc/conf.py b/doc/conf.py index 85886ef9f8..01f4c63c54 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['breathe', 'sphinx.ext.autodoc','rst2pdf.pdfbuilder'] +extensions = ['breathe', 'sphinx.ext.autodoc', 'rst2pdf.pdfbuilder', 'sphinx.ext.pngmath'] # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] @@ -304,4 +304,3 @@ def read_version(filename): 'project' : 'api', 'no-link' : False } - diff --git a/doc/docs.rst b/doc/docs.rst index 7dd4e252fb..d466cca30d 100644 --- a/doc/docs.rst +++ b/doc/docs.rst @@ -12,17 +12,17 @@ Contents: download compilation/index - commandline/index apps stages/index pipeline - vagranttutorial + vagrant community faq development/index tutorial/index api/index metadata + vagrant copyright Indices and tables diff --git a/doc/download.rst b/doc/download.rst index 8f89849d0a..b4405c5ff5 100644 --- a/doc/download.rst +++ b/doc/download.rst @@ -8,11 +8,20 @@ Download Current Release(s) ------------------------------------------------------------------------------ +* **2015-09-11** `PDAL-1.0.1-src.tar.gz`_ (`md5`_) + +.. _`PDAL-1.0.1-src.tar.gz`: http://download.osgeo.org/pdal/PDAL-1.0.1-src.tar.gz +.. _`md5`: http://download.osgeo.org/pdal/PDAL-1.0.1-src.tar.gz.md5 +.. _`DebianGIS`: http://wiki.debian.org/DebianGis Past Releases ------------------------------------------------------------------------------ +* **2015-09-10** `PDAL-1.0.0-src.tar.gz`_ + +.. _`PDAL-1.0.0-src.tar.gz`: http://download.osgeo.org/pdal/PDAL-1.0.0-src.tar.gz + .. _source: @@ -24,20 +33,20 @@ The main repository for PDAL is located on github at https://github.com/PDAL/PDA You can obtain a copy of the active source code by issuing the following command:: git clone git@github.com:PDAL/PDAL.git pdal - + Binaries ------------------------------------------------------------------------------ -A pre-1.0.0 release of PDAL is available via `OSGeo4W`_, however it is only -64-bit at this time. +A 1.0.0 release of PDAL is available via `OSGeo4W`_, however it is only +64-bit at this time. RPMs ................................................................................ RPMs for PDAL are available at http://pdal.s3-website-us-east-1.amazonaws.com/rpms/ - + .. _`OSGeo4W`: http://trac.osgeo.org/osgeo4w/ diff --git a/doc/faq.rst b/doc/faq.rst index 4a65611d12..f4a660c1d5 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -15,4 +15,24 @@ FAQ declarative pipeline syntax for orchestrating translation operations. PDAL can also use PCL through the :ref:`filters.pclblock` mechanism. +* What is PDAL's relationship to libLAS? + The idea behind libLAS was limited to LIDAR data and basic + manipulation. libLAS was also trying to be partially compatible + with LASlib and LAStools. PDAL, on the other hand, aims to be + a ultimate library and a set of tools for manipulating and processing + point clouds and is easily extensible by its users. + +* Are there any command line tools in PDAL similar to LAStools? + + Yes. The ``pdal`` command provides a wide range of features which go + far beyond basic LIDAR data processing. Additionally, PDAL is licensed + under an open source license (this applies to the whole library and + all command line tools). + +* 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`). diff --git a/doc/stages/filters.ferry.rst b/doc/stages/filters.ferry.rst index 3a9c5af6d2..1673c1a917 100644 --- a/doc/stages/filters.ferry.rst +++ b/doc/stages/filters.ferry.rst @@ -1,7 +1,7 @@ .. _filters.ferry: filters.ferry -============ +================================================================================ The ferry filter is used to stash intermediate variables as part of processing data. For example, a common scenario is to keep both the diff --git a/doc/stages/filters.greedyprojection.rst b/doc/stages/filters.greedyprojection.rst new file mode 100644 index 0000000000..7482a99b0b --- /dev/null +++ b/doc/stages/filters.greedyprojection.rst @@ -0,0 +1,20 @@ +.. _filters.greedyprojection: + +=============================================================================== +filters.greedyprojection +=============================================================================== + +The Greedy Projection filter passes data through the Point Cloud Library +(`PCL`_) GreedyProjectionTriangulation algorithm. + +GreedyProjectionTriangulation is an implementation of a greedy triangulation +algorithm for 3D points based on local 2D projections. It assumes locally smooth +surfaces and relatively smooth transitions between areas with different point +densities. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +None at the moment. Relying on defaults within PCL. diff --git a/doc/stages/filters.gridprojection.rst b/doc/stages/filters.gridprojection.rst new file mode 100644 index 0000000000..783c0b7f86 --- /dev/null +++ b/doc/stages/filters.gridprojection.rst @@ -0,0 +1,20 @@ +.. _filters.gridprojection: + +=============================================================================== +filters.gridprojection +=============================================================================== + +The Grid Projection filter passes data through the Point Cloud Library (`PCL`_) +GridProjection algorithm. + +GridProjection is an implementation of the surface reconstruction method +described in [Li2010]_. + +.. [Li2010] Li, Ruosi, et al. "Polygonizing extremal surfaces with manifold guarantees." Proceedings of the 14th ACM Symposium on Solid and Physical Modeling. ACM, 2010. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +None at the moment. Relying on defaults within PCL. diff --git a/doc/stages/filters.ground.rst b/doc/stages/filters.ground.rst new file mode 100644 index 0000000000..049259d3ac --- /dev/null +++ b/doc/stages/filters.ground.rst @@ -0,0 +1,42 @@ +.. _filters.ground: + +=============================================================================== +filters.ground +=============================================================================== + +The Ground filter passes data through the Point Cloud Library (`PCL`_) +ProgressiveMorphologicalFilter algorithm. + +ProgressiveMorphologicalFilter is an implementation of the method described in +[Zhang2003]_. + +.. [Zhang2003] Zhang, Keqi, et al. "A progressive morphological filter for removing nonground measurements from airborne LIDAR data." Geoscience and Remote Sensing, IEEE Transactions on 41.4 (2003): 872-882. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +maxWindowSize + Maximum window size. [Default: **33**] + +slope + Slope. [Default: **1.0**] + +maxDistance + Maximum distance. [Default: **2.5**] + +initialDistance + Initial distance. [Default: **0.15**] + +cellSize + Cell Size. [Default: **1**] + +classify + Apply classification labels? [Default: **true**] + +extract + Extract ground returns? [Default: **false**] + +approximate + Use approximate algorithm? [Default:: **false**] diff --git a/doc/stages/filters.merge.rst b/doc/stages/filters.merge.rst index 3aee80d0c5..08ea7b366e 100644 --- a/doc/stages/filters.merge.rst +++ b/doc/stages/filters.merge.rst @@ -1,13 +1,13 @@ .. _filters.merge: filters.merge -============ +=============================================================================== The merge filter combines input from multiple sources into a single output. No checks are made to ensure that points from the various sources have similar dimensions or are generally compatible. Notably, dimensions are not initialized when points merged from various sources do not have dimensions in -common. +common. Example ------- diff --git a/doc/stages/filters.mortonorder.rst b/doc/stages/filters.mortonorder.rst index a24e0ff384..60e8e4bc9f 100644 --- a/doc/stages/filters.mortonorder.rst +++ b/doc/stages/filters.mortonorder.rst @@ -1,7 +1,7 @@ .. _filters.mortonorder: filters.mortonorder -=========== +================================================================================ Sorts the XY data using `Morton ordering`_. diff --git a/doc/stages/filters.movingleastsquares.rst b/doc/stages/filters.movingleastsquares.rst new file mode 100644 index 0000000000..ef829e3968 --- /dev/null +++ b/doc/stages/filters.movingleastsquares.rst @@ -0,0 +1,22 @@ +.. _filters.movingleastsquares: + +=============================================================================== +filters.movingleastsquares +=============================================================================== + +The Moving Least Squares filter passes data through the Point Cloud Library +(`PCL`_) MovingLeastSquares algorithm. + +MovingLeastSquares is an implementation of the MLS (Moving Least Squares) +algorithm for data smoothing and improved normal estimation described in +[Alexa2003]_. It also contains methods for upsampling the resulting cloud based +on the parametric fit. + +.. [Alexa2003] Alexa, Marc, et al. "Computing and rendering point set surfaces." Visualization and Computer Graphics, IEEE Transactions on 9.1 (2003): 3-15. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +None at the moment. Relying on defaults within PCL. diff --git a/doc/stages/filters.poisson.rst b/doc/stages/filters.poisson.rst new file mode 100644 index 0000000000..54f6b06540 --- /dev/null +++ b/doc/stages/filters.poisson.rst @@ -0,0 +1,23 @@ +.. _filters.poisson: + +=============================================================================== +filters.poisson +=============================================================================== + +The Poisson filter passes data through the Point Cloud Library (`PCL`_) Poisson +surface reconstruction algorithm. + +Poisson is an implementation of the method described in [Kazhdan2006]_. + +.. [Kazhdan2006] Kazhdan, Michael, Matthew Bolitho, and Hugues Hoppe. "Poisson surface reconstruction." Proceedings of the fourth Eurographics symposium on Geometry processing. Vol. 7. 2006. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +depth + Maximum depth of the tree used for reconstruction. [Default: **8**] + +pointWeight + Importance of interpolation of point samples in the screened Poisson equation. [Default: **4.0**] diff --git a/doc/stages/filters.radiusoutlier.rst b/doc/stages/filters.radiusoutlier.rst new file mode 100644 index 0000000000..65c553ef22 --- /dev/null +++ b/doc/stages/filters.radiusoutlier.rst @@ -0,0 +1,31 @@ +.. _filters.radiusoutlier: + +=============================================================================== +filters.radiusoutlier +=============================================================================== + +The Radius Outlier filter passes data through the Point Cloud Library (`PCL`_) +RadiusOutlierRemoval algorithm. + +RadiusOutlierRemoval filters points in a cloud based on the number of neighbors +they have. Iterates through the entire input once, and for each point, retrieves +the number of neighbors within a certain radius. The point will be considered an +outlier if it has too few neighbors, as determined by ``min_neighbors``. The +radius can be changed using ``radius``. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +min_neighbors + Minimum number of neighbors in radius. [Default: **2**] + +radius + Radius. [Default: **1.0**] + +classify + Apply classification labels? [Default: **true**] + +extract + Extract ground returns? [Default: **false**] diff --git a/doc/stages/filters.splitter.rst b/doc/stages/filters.splitter.rst index 28917dcafe..91ac6c9653 100644 --- a/doc/stages/filters.splitter.rst +++ b/doc/stages/filters.splitter.rst @@ -1,7 +1,7 @@ .. _filters.splitter: filters.splitter -=============== +=============================================================================== The splitter filter breaks a point cloud into square tiles of a size that you choose. The origin of the tiles is chosen arbitrarily unless specified @@ -12,7 +12,7 @@ for each tile as its output. Splitting is usually applied to data read from files (which produce one large stream of points) before the points are written to a database (which prefer -data segmented into smaller blocks). +data segmented into smaller blocks). Example ------- @@ -40,10 +40,10 @@ Options length Length of the sides of the tiles that are created to hold points. [Default: 1000] - + origin_x X Origin of the tiles. [Default: none (chosen arbitarily)] origin_y Y Origin of the tiles. [Default: none (chosen arbitarily)] - + diff --git a/doc/stages/filters.statisticaloutlier.rst b/doc/stages/filters.statisticaloutlier.rst new file mode 100644 index 0000000000..d8d394e39d --- /dev/null +++ b/doc/stages/filters.statisticaloutlier.rst @@ -0,0 +1,40 @@ +.. _filters.statisticaloutlier: + +=============================================================================== +filters.statisticaloutlier +=============================================================================== + +The Statistical Outlier filter passes data through the Point Cloud Library +(`PCL`_) StatisticalOutlierRemoval algorithm. + +StatisticalOutlierRemoval uses point neighborhood statistics to filter outlier +data. The algorithm iterates through the entire input twice. During the first +iteration it will compute the average distance that each point has to its +nearest k neighbors. The value of k can be set using ``mean_k``. Next, the mean +and standard deviation of all these distances are computed in order to determine +a distance threshold. The distance threshold will be equal to: +:math:`mean + stddev_mult * stddev`. The multiplier for the standard deviation +can be set using ``multiplier``. During the next iteration the points will be +classified as inlier or outlier if their average neighbor distance is below or +above this threshold respectively. + +See [Rusu2008]_ for more information. + +.. [Rusu2008] Rusu, Radu Bogdan, et al. "Towards 3D point cloud based object maps for household environments." Robotics and Autonomous Systems 56.11 (2008): 927-941. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +mean_k + Mean number of neighbors. [Default: **2**] + +multiplier + Standard deviation threshold. [Default: **0.0**] + +classify + Apply classification labels? [Default: **true**] + +extract + Extract ground returns? [Default: **false**] diff --git a/doc/stages/filters.stats.rst b/doc/stages/filters.stats.rst index fa58692bd5..cf64244aa9 100644 --- a/doc/stages/filters.stats.rst +++ b/doc/stages/filters.stats.rst @@ -1,7 +1,7 @@ .. _filters.stats: filters.stats -============ +=============================================================================== The stats filter calculates the minimum, maximum and average (mean) values of dimensions. On request it will also provide an enumeration of values of @@ -41,7 +41,7 @@ Options dimensions A comma-separated list of dimensions whose statistics should be processed. If not provided, statistics for all dimensions are calculated. - + enumerate A comma-separated list of dimensions whose values should be enumerated. Note that this list does not add to the list of dimensions that may be diff --git a/doc/stages/filters.voxelgrid.rst b/doc/stages/filters.voxelgrid.rst new file mode 100644 index 0000000000..f45a686840 --- /dev/null +++ b/doc/stages/filters.voxelgrid.rst @@ -0,0 +1,30 @@ +.. _filters.voxelgrid: + +=============================================================================== +filters.voxelgrid +=============================================================================== + +The Voxel Grid filter passes data through the Point Cloud Library (`PCL`_) +VoxelGrid algorithm. + +VoxelGrid assembles a local 3D grid over a given PointCloud, and downsamples + +filters the data. The VoxelGrid class creates a *3D voxel grid* (think about a +voxel grid as a set of tiny 3D boxes in space) over the input point cloud data. +Then, in each *voxel* (i.e., 3D box), all the points present will be +approximated (i.e., *downsampled*) with their centroid. This approach is a bit +slower than approximating them with the center of the voxel, but it represents +the underlying surface more accurately. + +.. _`PCL`: http://www.pointclouds.org + +Options +------------------------------------------------------------------------------- + +leaf_x + Leaf size in X dimension. [Default: **1.0**] + +leaf_y + Leaf size in Y dimension. [Default: **1.0**] + +leaf_z + Leaf size in Z dimension. [Default: **1.0**] diff --git a/doc/stages/index.rst b/doc/stages/index.rst index a032f21669..2e5dce0a74 100644 --- a/doc/stages/index.rst +++ b/doc/stages/index.rst @@ -10,65 +10,24 @@ Readers .. toctree:: :maxdepth: 1 + :glob: - readers.buffer - readers.faux - readers.geowave - readers.greyhound - readers.las - readers.mrsid - readers.nitf - readers.oci - readers.optech - readers.pcd - readers.pgpointcloud - readers.ply - readers.qfit - readers.rxp - readers.sbet - readers.sqlite + readers.* Writers ======= .. toctree:: :maxdepth: 1 + :glob: - writers.derivative - writers.geowave - writers.las - writers.matlab - writers.nitf - writers.oci - writers.ply - writers.p2g - writers.pcd - writers.pgpointcloud - writers.pclvisualizer - writers.rialto - writers.sqlite - writers.text + writers.* Filters ======= .. toctree:: :maxdepth: 1 + :glob: - filters.attribute - filters.colorization - filters.chipper - filters.crop - filters.decimation - filters.ferry - filters.hexbin - filters.mortonorder - filters.merge - filters.pclblock - filters.predicate - filters.programmable - filters.range - filters.reprojection - filters.sort - filters.stats - filters.transformation + filters.* diff --git a/doc/stages/readers.bpf.rst b/doc/stages/readers.bpf.rst index 5230c56d7b..0d70e28bc0 100644 --- a/doc/stages/readers.bpf.rst +++ b/doc/stages/readers.bpf.rst @@ -3,8 +3,9 @@ readers.bpf =========== -The **BPF Reader** supports reading from BPF files that are encoded as -version 1, 2 or 3. +BPF is an NGA specification for point cloud data. The specification can be +found at https://nsgreg.nga.mil/doc/view?i=4202 The **BPF Reader** supports +reading from BPF files that are encoded as version 1, 2 or 3. This BPF reader only supports Zlib compression. It does NOT support the deprecated compression types QuickLZ and FastLZ. The reader will consume files @@ -33,5 +34,5 @@ Options ------- filename - BPF file to read [Required] + BPF file to read [Required] diff --git a/doc/stages/readers.buffer.rst b/doc/stages/readers.buffer.rst index 7dc11fa1f5..4afc03d4a0 100644 --- a/doc/stages/readers.buffer.rst +++ b/doc/stages/readers.buffer.rst @@ -1,9 +1,9 @@ -.. _readers.buffer. +.. _readers.buffer: readers.buffer ============== -The `readers.buffer`_ stage is a special stage that allows +The :ref:`readers.buffer` stage is a special stage that allows you to read data from your own PointView rather than fetching the data from a specific reader. In the :ref:`writing` example, it is used to take a simple listing of points and turn them into an @@ -13,7 +13,7 @@ LAS file. Example ------- -See :ref:`writing` for an example usage scenario for `readers.buffer`. +See :ref:`writing` for an example usage scenario for :ref:`readers.buffer`. Options ------- diff --git a/doc/stages/readers.gdal.rst b/doc/stages/readers.gdal.rst new file mode 100644 index 0000000000..23e3b986c0 --- /dev/null +++ b/doc/stages/readers.gdal.rst @@ -0,0 +1,92 @@ +.. _readers.gdal: + +readers.gdal +================================================================================ + +The `GDAL`_ reader reads `GDAL readable raster`_ datasources as point clouds. + +.. _`GDAL`: http://gdal.org +.. _`GDAL readable raster`: http://www.gdal.org/formats_list.html + +Each pixel is given an X and Y coordinate (and corresponding PDAL dimensions) that +are center pixel, and each band is represented by "band-1", "band-2", or "band-n". The +user must know what the bands correspond to, and use :ref:`filters.ferry` to copy data into +known dimensions as needed. + + +Basic Example +-------------------------------------------------------------------------------- + +.. code-block:: xml + + + + + + + + + + + +LAS Example +-------------------------------------------------------------------------------- + +The following example writes a JPG as an `ASPRS LAS`_ file. + +.. _`ASPRS LAS`: http://www.asprs.org/Committee-General/LASer-LAS-File-Format-Exchange-Activities.html + +.. code-block:: xml + + + + + + + + + + + + + + + + + +Options +-------------------------------------------------------------------------------- + +filename + GDALOpen'able raster file to read [Required] + + diff --git a/doc/stages/readers.geowave.rst b/doc/stages/readers.geowave.rst index f991da56c7..4c8852099e 100644 --- a/doc/stages/readers.geowave.rst +++ b/doc/stages/readers.geowave.rst @@ -1,9 +1,11 @@ .. _readers.geowave: readers.geowave -============ +=============================================================================== -The **GeoWave reader** uses `GeoWave`_ to read from Accumulo. GeoWave entries are stored using EPSG:4326. Instructions for configuring the GeoWave plugin can be found `here`_ +The **GeoWave reader** uses `GeoWave`_ to read from Accumulo. GeoWave entries +are stored using EPSG:4326. Instructions for configuring the GeoWave plugin +can be found `here`_ Example ------- @@ -57,7 +59,7 @@ pointsPerEntry Sets the maximum number of points per Accumulo entry when using FeatureCollectionDataAdapter. [Default: 5000u] bounds - The extent of the bounding rectangle to use to query points, expressed as a string, eg: “([xmin,xmax],[ymin,ymax],[zmin,zmax])”. [Default: unit cube] + The extent of the bounding rectangle to use to query points, expressed as a string, eg: “([xmin,xmax],[ymin,ymax],[zmin,zmax])”. [Default: unit cube] .. _GeoWave: https://ngageoint.github.io/geowave/ diff --git a/doc/stages/writers.bpf.rst b/doc/stages/writers.bpf.rst index 0efd2a83d1..91b3a8a344 100644 --- a/doc/stages/writers.bpf.rst +++ b/doc/stages/writers.bpf.rst @@ -3,7 +3,9 @@ writers.bpf =========== -The **BPF Writer** supports writing of version 3 BPF format files. +BPF is an NGA specification for point cloud data. The specification can be +found at https://nsgreg.nga.mil/doc/view?i=4202 The PDAL **BPF Writer** +only supports writing of version 3 BPF format files. Example ------- @@ -28,56 +30,60 @@ Options ------- filename - BPF file to read. The writer will accept a filename containing - a single placeholder character ('#'). If input to the writer consists - of multiple PointViews, each will be written to a separate file, where - the placeholder will be replaced with an incrementing integer. If no - placeholder is found, all PointViews provided to the writer are - aggregated into a single file for output. Multiple PointViews are usually - the result of using :ref:`filters.splitter` or :ref:`filters.chipper`. - [Required] + BPF file to read. The writer will accept a filename containing + a single placeholder character ('#'). If input to the writer consists + of multiple PointViews, each will be written to a separate file, where + the placeholder will be replaced with an incrementing integer. If no + placeholder is found, all PointViews provided to the writer are + aggregated into a single file for output. Multiple PointViews are usually + the result of using :ref:`filters.splitter` or :ref:`filters.chipper`. + [Required] compression - This option can be set to true to cause the file to be written with Zlib - compression as described in the BPF specification. [Default: false] + This option can be set to true to cause the file to be written with Zlib + compression as described in the BPF specification. [Default: false] format - Specifies the format for storing points in the file. [Default: dim] + Specifies the format for storing points in the file. [Default: dim] - * dim == Dimension-major (non-interleaved). All data for a single dimension - are stored contiguously. - * point == Point-major (interleaved). All data for a single point are stored - contiguously. - * byte == Byte-major (byte-segregated). All data for a single dimension are - stored contiguously, but bytes are arranged such that the first bytes for - all points are stored contiguously, followed by the second bytes of all - points, etc. See the BPF specification for further information. + * dim == Dimension-major (non-interleaved). All data for a single dimension + are stored contiguously. + * point == Point-major (interleaved). All data for a single point are stored + contiguously. + * byte == Byte-major (byte-segregated). All data for a single dimension are + stored contiguously, but bytes are arranged such that the first bytes for + all points are stored contiguously, followed by the second bytes of all + points, etc. See the BPF specification for further information. bundledfile - Path of file to be written as a bundled file (see specification). The path - part of the filespec is removed and the filename is stored as part of the - data. This option can be specified as many times as desired. + Path of file to be written as a bundled file (see specification). The path + part of the filespec is removed and the filename is stored as part of the + data. This option can be specified as many times as desired. header_data - Base64-encoded data that will be decoded and written following the - standard BPF header. + Base64-encoded data that will be decoded and written following the + standard BPF header. coord_id - The coordinate ID (UTM zone) of the data. NOTE: Only the UTM coordinate - type is currently supported. [Default: 0, with coordinate type set to none] + The coordinate ID (UTM zone) of the data. NOTE: Only the UTM coordinate + type is currently supported. [Default: 0, with coordinate type set to none] scale_x, scale_y, scale_z - Scale to be divided from the X, Y and Z nominal values, respectively, after - the offset has been applied. The special value "auto" can be specified, - which causes the writer to select a scale to set the stored values of the - dimensions to range from [0, 2147483647]. [Default: .01] + Scale to be divided from the X, Y and Z nominal values, respectively, after + the offset has been applied. The special value "auto" can be specified, + which causes the writer to select a scale to set the stored values of the + dimensions to range from [0, 2147483647]. [Default: .01] - Note: written value = (nominal value - offset) / scale. + .. note:: + + written value = (nominal value - offset) / scale. offset_x, offset_y, offset_z - Offset to be subtracted from the X, Y and Z nominal values, respectively, - before the value is scaled. The special value "auto" can be specified, - which causes the writer to set the offset to the minimum value of the - dimension. [Default: 0] + Offset to be subtracted from the X, Y and Z nominal values, respectively, + before the value is scaled. The special value "auto" can be specified, + which causes the writer to set the offset to the minimum value of the + dimension. [Default: 0] + + .. note:: - Note: written value = (nominal value - offset) / scale. + written value = (nominal value - offset) / scale. diff --git a/doc/stages/writers.las.rst b/doc/stages/writers.las.rst index 3d522fdb69..b929a4f4ac 100644 --- a/doc/stages/writers.las.rst +++ b/doc/stages/writers.las.rst @@ -35,7 +35,7 @@ filename the placeholder will be replaced with an incrementing integer. If no placeholder is found, all PointViews provided to the writer are aggregated into a single file for output. Multiple PointViews are usually - the result of using :ref:`filters.splitter` or :ref:`filters.chipper`. + the result of using :ref:`filters.splitter` or :ref:`filters.chipper`. [Required] forward @@ -50,11 +50,22 @@ forward which is equivalent to specifying all the values EXCEPT the scale and offset values. Scale and offset values can be forwarded as a group by using the special values 'scale' and 'offset' respectively. The special - value 'all' is equivalent to specifying 'header', 'scale' and 'offset'. - If an option is specified explicitly, it will override any forwarded value. - If a LAS file is the result of multiple LAS input files, the values to be - forwarded must match or they will be ignored. - + value 'all' is equivalent to specifying 'header', 'scale', 'offset' and + 'vlr' (see below). + If a header option is specified explicitly, it will override any forwarded + header value. + If a LAS file is the result of multiple LAS input files, the header values + to be forwarded must match or they will be ignored and a default will + be used instead. + + VLRs can be forwarded by using the special value 'vlr'. VLRs containing + the following User IDs are NOT forwarded: 'LASF_Projection', 'LASF_Spec', + 'liblas', 'laszip encoded'. These VLRs are known to contain information + regarding the formatting of the data and will be rebuilt properly in the + output file as necessary. Unlike header values, VLRs from multiple input + files are accumulated and each is written to the output file. Forwarded + VLRs may contain duplicate User ID/Record ID pairs. + minor_version All LAS files are version 1, but the minor version (0 - 4) can be specified with this option. [Default: 3] @@ -66,18 +77,18 @@ software_id creation_doy Number of the day of the year (January 1 == 0, Dec 31 == 365) this file is being created. - + creation_year Year (Gregorian) this file is being created. - + dataformat_id Controls whether information about color and time are stored with the point information in the LAS file. [Default: 3] - + * 0 == no color or time stored * 1 == time is stored * 2 == color is stored - * 3 == color and time are stored + * 3 == color and time are stored * 4 [Not Currently Supported] * 5 [Not Currently Supported] * 6 == time is stored (version 1.4+ only) @@ -85,13 +96,13 @@ dataformat_id * 8 == time, color and near infrared are stored (version 1.4+ only) * 9 [Not Currently Supported] * 10 [Not Currently Supported] - + system_id String identifying the system that created this LAS file. [Default: "PDAL"] - + a_srs The spatial reference system of the file to be written. Can be an EPSG string (eg "EPSG:268910") or a WKT string. [Default: Not set] - + global_encoding Various indicators to describe the data. See the LAS documentation. Note that PDAL will always set bit four when creating LAS version output. @@ -120,7 +131,7 @@ offset_x, offset_y, offset_z dimension. [Default: 0] Note: written value = (nominal value - offset) / scale. - + filesource_id The file source id number to use for this file (a value between 1 and 65535) [Default: 0] @@ -134,11 +145,11 @@ extra_dims Extra dimensions to be written as part of each point beyond those specified by the LAS point format. The format of the option is =, ... where type is one of: - int8, int16, int32, int64, uint8, uint16, uint32, uint64, float, double + int8, int16, int32, int64, uint8, uint16, uint32, uint64, float, double '_t' may be added to any of the type names as well (e.g., uint32_t). When the version of the output file is specified as 1.4 or greater, an extra bytes VLR (User ID: LASF_Spec, Record ID: 4), is created that describes the extra dimensions specified by this option. .. _LAS format: http://asprs.org/Committee-General/LASer-LAS-File-Format-Exchange-Activities.html - + diff --git a/doc/stages/writers.null.rst b/doc/stages/writers.null.rst index 7f7d90df7a..bf11c95ff0 100644 --- a/doc/stages/writers.null.rst +++ b/doc/stages/writers.null.rst @@ -1,4 +1,4 @@ -.. _writers.text: +.. _writers.null: writers.null ============ diff --git a/doc/stages/writers.text.rst b/doc/stages/writers.text.rst index e7e8c26f65..a8a4e32188 100644 --- a/doc/stages/writers.text.rst +++ b/doc/stages/writers.text.rst @@ -3,7 +3,9 @@ writers.text ============ -The **text writer** writes out to a text file. This is useful for debugging or getting smaller files into an easily parseable format. The text writer supports both `GeoJson`_ and `CSV`_ output. +The **text writer** writes out to a text file. This is useful for debugging or +getting smaller files into an easily parseable format. The text writer +supports both `GeoJSON`_ and `CSV`_ output. Example @@ -33,27 +35,27 @@ filename File to write to, or "STDOUT" to write to standard out [Required] format - Output format to use. One of "geojson" or "csv". [Default: **csv**] + Output format to use. One of "geojson" or "csv". [Default: **csv**] order Comma-separated list of dimension names, giving the desired column order in the output file, for example "X,Y,Z,Red,Green,Blue". [Default: none] - + keep_unspecified Should we output any fields that are not specified in the dimension order? [Default: **true**] jscallback When producing GeoJSON, the callback allows you to wrap the data in a function, so the output can be evaluated in a