diff --git a/doc/apps/cmdline.txt b/doc/apps/cmdline.txt index 786ddc8c7b..7c13aff8fc 100644 --- a/doc/apps/cmdline.txt +++ b/doc/apps/cmdline.txt @@ -1,8 +1,8 @@ -.. _apps_cmdline: +.. _apps: -========================= +****************************************************************************** Apps -========================= +****************************************************************************** PDAL will contain a number of command line applications that are built on top of the PDAL libraries. This Note lists those apps. @@ -11,7 +11,7 @@ This should be fleshed out to list the (major) options for each of the apps. App Commonality -=============== +------------------------------------------------------------------------------ The following notes apply to all apps: @@ -26,15 +26,21 @@ The following notes apply to all apps: * describe common switches: --version, --help, --verbose pc2pc -===== +------------------------------------------------------------------------------ Converts from one file format to another, optionally with some (relatively simple) filtering or processing. +.. _pdal_test: + +pdal_test +------------------------------------------------------------------------------ + +some text pcinfo -====== +------------------------------------------------------------------------------ Dumps information about a point cloud file, such as: @@ -56,7 +62,7 @@ XML or similar, where it makes sense to do so. pcpipeline -========== +------------------------------------------------------------------------------ [tbd] @@ -71,29 +77,3 @@ should work under Unix too. -pcindex -======= - -(future) - -Creates a serialized spatial index for a point cloud. First pass at this -is to repurpose liblas::Index which supports serialization. - - - -pcmerge -======= - -(future -- likely to be part of pc2pc) - -Merges multiple files together. (This is also known as mosacking.) - - - -pctile -====== - -(future -- likely to be part of pc2pc) - -Chops one file up into multiple files. This could be the liblas::Chipper, -leaf nodes of an index like an R-tree, or a simple quadtree build. diff --git a/doc/development/dependencies.txt b/doc/building/dependencies.txt similarity index 98% rename from doc/development/dependencies.txt rename to doc/building/dependencies.txt index e7e756bdd1..ed390d9ade 100644 --- a/doc/development/dependencies.txt +++ b/doc/building/dependencies.txt @@ -22,7 +22,7 @@ Boost ------------------------------------------------------------------------------ PDAL attempts to constrain its code-love for Boost and not always try to -use the latest and the greatest, but instinct is hard to control. Specifically, +use the latest and the greatest, but the instinct is hard to control. Specifically, PDAL takes advantage of a number of late-version features in boost::accumulators for statistics filtering, and as of this writing, it should be assumed that the minimum version required for Boost is 1.48. Other versions less than that diff --git a/doc/building/index.txt b/doc/building/index.txt index 5768e721ad..18f054331a 100644 --- a/doc/building/index.txt +++ b/doc/building/index.txt @@ -1,7 +1,7 @@ .. _building: ****************************************************************************** -Building and Installing +Installation ****************************************************************************** This section describes how to build and install PDAL under Windows, Linux, and Mac. @@ -11,7 +11,7 @@ Contents: .. toctree:: :maxdepth: 1 + unix windows - linux - mac + dependencies \ No newline at end of file diff --git a/doc/building/linux.txt b/doc/building/linux.txt deleted file mode 100644 index 3061350c0a..0000000000 --- a/doc/building/linux.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _building_linux: - -===================== -Bulding under Linux -===================== - -to be written diff --git a/doc/building/mac.txt b/doc/building/mac.txt deleted file mode 100644 index a629f2e11e..0000000000 --- a/doc/building/mac.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _building_mac: - -===================== -Bulding under Mac -===================== - -to be written diff --git a/doc/building/media/ccmake-osx-start.png b/doc/building/media/ccmake-osx-start.png new file mode 100644 index 0000000000..6b399ac5fd Binary files /dev/null and b/doc/building/media/ccmake-osx-start.png differ diff --git a/doc/building/media/cmake-gui-osx-configured.png b/doc/building/media/cmake-gui-osx-configured.png new file mode 100644 index 0000000000..f6a8f51cdc Binary files /dev/null and b/doc/building/media/cmake-gui-osx-configured.png differ diff --git a/doc/building/media/cmake-gui-osx-start.png b/doc/building/media/cmake-gui-osx-start.png new file mode 100644 index 0000000000..2690b80820 Binary files /dev/null and b/doc/building/media/cmake-gui-osx-start.png differ diff --git a/doc/building/media/xcode-lasinfo-arguments.png b/doc/building/media/xcode-lasinfo-arguments.png new file mode 100644 index 0000000000..87f8a939e5 Binary files /dev/null and b/doc/building/media/xcode-lasinfo-arguments.png differ diff --git a/doc/building/media/xcode-set-default-executable.png b/doc/building/media/xcode-set-default-executable.png new file mode 100644 index 0000000000..a123ce2a8d Binary files /dev/null and b/doc/building/media/xcode-set-default-executable.png differ diff --git a/doc/building/media/xcode-start.png b/doc/building/media/xcode-start.png new file mode 100644 index 0000000000..5e4dbe03fa Binary files /dev/null and b/doc/building/media/xcode-start.png differ diff --git a/doc/building/unix.txt b/doc/building/unix.txt new file mode 100644 index 0000000000..f000d8364c --- /dev/null +++ b/doc/building/unix.txt @@ -0,0 +1,300 @@ +.. _building_unix: + +****************************************************************************** +Unix Compilation +****************************************************************************** + +:Author: Howard Butler +:Contact: hobu.inc at gmail dot com +:Date: 3/19/2012 + +`CMake`_ 2.8.6+ is the prescribed tool for building from source as well as +running unit tests. `CMake`_ is a cross-platform build system that provides a +number of benefits, and its usage ensures a single, up-to-date build system +for all PDAL-supported operating systems and compiler platforms. + +Like a combination of autoconf/autotools, except that it actually works on +Windows (and works without eye-stabbing pain in general), `CMake`_ is somewhat +of a meta-building tool. It can be used to generate MSVC project files, GNU +Makefiles, NMake files for MSVC, XCode projects on Mac OS X, and Eclipse +projects (as well as many others). This functionality allows the PDAL project +to avoid maintaining these build options by hand and target a single configuration +and build platform. + +This tutorial will describe how to build PDAL using CMake on both a +Unix platform. + + +:ref:`dependencies` contains more information about specific library version +requirements and notes about building or acquiring them. + +Using "Unix Makefiles" on Linux +.............................................................................. + +Get the source code +------------------------------------------------------------------------------ + +See :ref:`source` for how to obtain the latest development version or visit +:ref:`download` to get the latest released version. + +Prepare a build directory +------------------------------------------------------------------------------ + +CMake allows you to generate different builders for a project, and in this +example, we are going to generate a "Unix Makefiles" builder +for PDAL on Mac OS X. + +:: + + $ cd PDAL + $ mkdir makefiles + $ cd makefiles + +Configure base library +------------------------------------------------------------------------------ + +Configure the basic core library for the "Unix Makefiles" target: + +:: + + $ cmake -G "Unix Makefiles" ../ + -- The C compiler identification is GNU + -- The CXX compiler identification is GNU + -- Checking whether C compiler has -isysroot + -- Checking whether C compiler has -isysroot - yes + -- Check for working C compiler: /usr/bin/gcc + -- Check for working C compiler: /usr/bin/gcc -- works + -- Detecting C compiler ABI info + -- Detecting C compiler ABI info - done + -- Checking whether CXX compiler has -isysroot + -- Checking whether CXX compiler has -isysroot - yes + -- Check for working CXX compiler: /usr/bin/c++ + -- Check for working CXX compiler: /usr/bin/c++ -- works + -- Detecting CXX compiler ABI info + -- Detecting CXX compiler ABI info - done + -- Enable PDAL utilities to build - done + -- Configuring done + -- Generating done + -- Build files have been written to: /Users/hobu/hg/PDAL-cmake/makefiles + +Issue the `make` command +------------------------------------------------------------------------------ + +This will build a base build of the library, with no extra libraries being +configured. + + +.. _make_install: + +Run ``make install`` and test your installation with a :ref:`pdal_test` command +------------------------------------------------------------------------------ + +``make install`` will install the :ref:`utilities ` in the location +that was specified for 'CMAKE_INSTALL_PREFIX'. Once installed, ensure that +you can run pcinfo. + + +.. _configure_optional_libraries: + +Configure your :ref:`Optional Libraries `. +------------------------------------------------------------------------------ + +By checking the "on" button for each, CMake may find your installations of +these libraries, but in case it does not, set the following variables, +substituting accordingly, to values that match your system layout. + +.. csv-table:: + + "`GDAL`_","GDAL_CONFIG", "/usr/local/bin/gdal-config" + "","GDAL_INCLUDE_DIR", "/usr/local/include" + "","GDAL_LIBRARY", "/usr/local/lib/libgdal.so" + "`GeoTIFF`_","GEOTIFF_INCLUDE_DIR","/usr/local/include" + "","GEOTIFF_LIBRARY","/usr/local/lib/libgeotiff.so" + "`OCI`_","ORACLE_INCLUDE_DIR","/home/oracle/sdk/include" + "","ORACLE_NNZ_LIBRARY","/home/oracle/libnnz10.so" + "","ORACLE_OCCI_LIBRARY","/home/oracle/libocci.so" + "","ORACLE_OCIEI_LIBRARY","/home/oracle/libociei.so" + "","ORACLE_OCI_LIBRARY","/home/oracle/libclntsh.so" + +.. _GDAL: http://www.gdal.org +.. _Proj.4: http://trac.osgeo.org/proj +.. _GeoTIFF: http://trac.osgeo.org/geotiff +.. _libxml2: http://xmlsoft.org +.. _`OCI`: http://www.oracle.com/technology/tech/oci/index.html +.. _`Oracle Instant Client`: http://www.oracle.com/technology/tech/oci/instantclient/index.html +.. _`Oracle Point Cloud`: http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28400/sdo_pc_pkg_ref.htm +.. _`DebianGIS`: http://wiki.debian.org/DebianGis +.. _`Debian`: http://www.debian.org +.. _`KyngChaos`: http://www.kyngchaos.com/software/unixport +.. _`OSGeo4W`: http://trac.osgeo.org/osgeo4w/ + + +CCMake and cmake-gui +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + The following was just swiped from the libLAS compilation document + and it has not been updated for PDAL. The basics should be the same, however. + Please ask on the :ref:`mailing list` programs + +:: + + make install + +Using "XCode" on OS X +.............................................................................. + + +Get the source code +------------------------------------------------------------------------------ + +See :ref:`source` for how to obtain the latest development version or visit +:ref:`download` to get the latest released version. + +Prepare a build directory +------------------------------------------------------------------------------ + +CMake allows you to generate different builders for a project, and in this +example, we are going to generate an "Xcode" builder for PDAL on Mac OS X. +Additionally, we're going to use an alternative compiler -- `LLVM`_ -- which +under certain situations can produce much faster code on Mac OS X. + +:: + + $ export CC=/usr/bin/llvm-gcc + $ export CXX=/usr/bin/llvm-g++ + $ cd PDAL + $ mkdir xcode + $ cd xcode/ + +Configure base library +------------------------------------------------------------------------------ + +Configure the basic core library for the Xcode build: + +:: + + $ cmake -G "Xcode" .. + -- The C compiler identification is GNU + -- The CXX compiler identification is GNU + -- Checking whether C compiler has -isysroot + -- Checking whether C compiler has -isysroot - yes + -- Check for working C compiler: /usr/bin/llvm-gcc + -- Check for working C compiler: /usr/bin/llvm-gcc -- works + -- Detecting C compiler ABI info + -- Detecting C compiler ABI info - done + -- Checking whether CXX compiler has -isysroot + -- Checking whether CXX compiler has -isysroot - yes + -- Check for working CXX compiler: /usr/bin/llvm-g++ + -- Check for working CXX compiler: /usr/bin/llvm-g++ -- works + -- Detecting CXX compiler ABI info + -- Detecting CXX compiler ABI info - done + -- Enable PDAL utilities to build - done + -- Enable PDAL unit tests to build - done + -- Configuring done + -- Generating done + -- Build files have been written to: /Users/hobu/hg/PDAL-cmake/xcode + + +Alternatively, if you have `KyngChaos`_ frameworks for `GDAL`_ and +`GeoTIFF`_ installed, you can provide locations for those as part of your +``cmake`` invocation: + +:: + + $ cmake -G "Xcode" \ + -D GDAL_CONFIG=/Library/Frameworks/GDAL.framework/Programs/gdal-config \ + -D GEOTIFF_INCLUDE_DIR=/Library/Frameworks/UnixImageIO.framework/unix/include \ + -D GEOTIFF_LIBRARY=/Library/Frameworks/UnixImageIO.framework/unix/lib/libgeotiff.dylib \ + .. + + +:: + + $ open PDAL.xcodeproj/ + +.. figure:: media/xcode-start.png + :alt: Building PDAL using the XCode project + +Set default command for XCode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the default executable for the project to be ``lasinfo`` by opening the +"Executables" tree, choosing "lasinfo," and clicking the bubble next to +the "Executable name" in the right-hand panel. + +.. figure:: media/xcode-set-default-executable.png + :alt: Setting the default executable + +Set arguments for :ref:`pdal_test` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the arguments for :ref:`pdal_test` so it can be run from within XCode. We +use the ${PROJECT_DIR} environment variable to be able to tell pdal_test the +location of our test file. This is similar to the :ref:`same command +` above in the "Unix Makefiles" section. + +.. figure:: media/xcode-lasinfo-arguments.png + :alt: Setting the arguments for lasinfo + + + +Configure :ref:`Optional Libraries ` +------------------------------------------------------------------------------ + +As :ref:`before `, use ``ccmake ../`` or ``cmake-gui ../`` to +configure your :ref:`dependencies`. + + +.. figure:: media/cmake-gui-osx-configured.png + :alt: Configuring optional libraries with CMake GUI + + +.. _`CMake`: http://www.cmake.org/ +.. _`CTest`: http://cmake.org/cmake/help/ctest-2-8-docs.html +.. _`CMake 2.8.0+`: http://www.cmake.org/cmake/help/cmake-2-8-docs.html +.. _`CDash`: http://www.cdash.org/ +.. _`continuous integration`: http://en.wikipedia.org/wiki/Continuous_integration +.. _`PDAL CDash`: http://my.cdash.org/index.php?project=PDAL +.. _`Curses`: http://en.wikipedia.org/wiki/Curses_%28programming_library%29 +.. _`Autoconf`: http://www.gnu.org/software/autoconf/ +.. _`LLVM`: http://llvm.org/ +.. _`OSGeo4W`: http://trac.osgeo.org/osgeo4w/ +.. _`Boost`: http://www.boost.org/ + diff --git a/doc/development/index.txt b/doc/development/index.txt index d2b6620349..c7608a0cd7 100644 --- a/doc/development/index.txt +++ b/doc/development/index.txt @@ -20,7 +20,6 @@ Contents: .. toctree:: :maxdepth: 2 - dependencies bindings building conventions diff --git a/doc/development/source.txt b/doc/development/source.txt new file mode 100644 index 0000000000..991d1c8d02 --- /dev/null +++ b/doc/development/source.txt @@ -0,0 +1,12 @@ +.. _source: + +****************************************************************************** +PDAL Source Repository +****************************************************************************** + +The main repository for PDAL is located on github at https://github.com/PDAL/PDAL + +You can obtain a copy of the active source code by issuing the following command:: + + git clone git@github.com:PDAL/PDAL.git pdal + diff --git a/doc/docs.txt b/doc/docs.txt index ff4f4b9953..2547a38451 100644 --- a/doc/docs.txt +++ b/doc/docs.txt @@ -10,7 +10,7 @@ Contents: .. toctree:: :maxdepth: 2 - index + download building/index tutorial/index apps/index diff --git a/doc/other/download.txt b/doc/download.txt similarity index 98% rename from doc/other/download.txt rename to doc/download.txt index b07d5c90a3..8b5e0803c9 100644 --- a/doc/other/download.txt +++ b/doc/download.txt @@ -1,4 +1,4 @@ -.. _other_download: +.. _download: ****************************************************************************** Download diff --git a/doc/other/index.txt b/doc/other/index.txt index abe2186ab8..8ee8c32ce1 100644 --- a/doc/other/index.txt +++ b/doc/other/index.txt @@ -10,7 +10,6 @@ Other PDAL documentation community faq - download features