[Liblas-commits] hg: c++ tutorial updates to bring in line with how
the code beha...
liblas-commits at liblas.org
liblas-commits at liblas.org
Tue Feb 22 11:57:58 EST 2011
details: http://hg.liblas.orghg/rev/b7c79f4eec6f
changeset: 2885:b7c79f4eec6f
user: Howard Butler <hobu.inc at gmail.com>
date: Tue Feb 22 10:57:51 2011 -0600
description:
c++ tutorial updates to bring in line with how the code behaves now
diffstat:
doc/tutorial/cpp.txt | 349 ++++++++++++++++++++++++++++++++++----------------
1 files changed, 233 insertions(+), 116 deletions(-)
diffs (truncated from 504 to 300 lines):
diff -r 4809a0506ae8 -r b7c79f4eec6f doc/tutorial/cpp.txt
--- a/doc/tutorial/cpp.txt Mon Feb 21 15:54:04 2011 -0500
+++ b/doc/tutorial/cpp.txt Tue Feb 22 10:57:51 2011 -0600
@@ -4,126 +4,203 @@
C++ Tutorial
*********************************************
+
+
+
+:Author: Mateusz Loskot
+:Contact: mateusz at loskot dot net
+:Author: Howard Butler
+:Contact: hobu.inc at gmail dot com
+:Date: 2/22/2011
+
+.. contents::
+ :depth: 2
+ :backlinks: none
+
This basic tutorial explains how to use libLAS to read and write LIDAR data
encoded in LAS File Format. For more examples in C++, check source of `unit
tests package`_ for libLAS.
-
-.. note::
- This tutorial needs to be extended with more detailed instructions and examples.
-
-=============================================
-Reading
-=============================================
+==============================================================================
+Reading LAS data using ``liblas::Reader``
+==============================================================================
1. Include required header files from libLAS and C++ Standard Library
-.. code-block:: cpp
+ .. code-block:: cpp
- #include <liblas/laspoint.hpp>
- #include <liblas/lasreader.hpp>
- #include <fstream> // std::ifstream
- #include <iostream> // std::cout
+ #include <liblas/liblas.hpp>
+ #include <fstream> // std::ifstream
+ #include <iostream> // std::cout
2. Create input stream and associate it with .las file opened to read in
**binary** mode
-.. code-block:: cpp
+ .. code-block:: cpp
- std::ifstream ifs;
- ifs.open("file.las", std::ios::in | std::ios::binary);
+ std::ifstream ifs;
+ ifs.open("file.las", std::ios::in | std::ios::binary);
-3. Instantiate LAS file reader attached to the input stream object
+3. Create a ReaderFactory and instantiate a new liblas::Reader using
+ the stream.
-.. code-block:: cpp
+ .. code-block:: cpp
- liblas::Reader reader(ifs);
+ liblas::ReaderFactory f;
+ liblas::Reader reader = f.CreateWithStream(ifs);
+
+ .. note::
+ It is possible to use the basic liblas::Reader constructor that
+ takes in a std::istream, but it will not be able to account for the fact
+ that the file might be compressed. Using the ReaderFactory will take
+ care of all of this for you.
4. After the reader has been created, you can access members of the Public
Header Block
-.. code-block:: cpp
+ .. code-block:: cpp
- liblas::Header const& header = reader.GetHeader();
+ liblas::Header const& header = reader.GetHeader();
- std::cout << "Signature: " << header.GetFileSignature() << '\n';
- std::cout << "Points count: " << header.GetPointRecordsCount() << '\n';
+ std::cout << "Compressed: " << (header.Compressed() == true) ? "true":"false";
+ std::cout << "Signature: " << header.GetFileSignature() << '\n';
+ std::cout << "Points count: " << header.GetPointRecordsCount() << '\n';
-.. note::
- It's correct to assume that after successful instantiation of reader,
- public header block is automatically accessible. In other words, there
- never be a reader that can not serve a header data.
+ .. note::
+ It's correct to assume that after successful instantiation of reader, the
+ public header block is automatically accessible. In other words, there
+ never be a reader that can not serve a header data.
-5. And, iterate through point records
+5. Iterate through point records
-.. code-block:: cpp
+ .. code-block:: cpp
- while (reader.ReadNextPoint())
- {
- liblas::Point const& p = reader.GetPoint();
+ while (reader.ReadNextPoint())
+ {
+ liblas::Point const& p = reader.GetPoint();
- std::cout << p.GetX() << ", " << p.GetY() << ", " << p.GetZ() << "\n";
- }
+ std::cout << p.GetX() << ", " << p.GetY() << ", " << p.GetZ() << "\n";
+ }
-=============================================
-Writing
-=============================================
+6. Randomly read point 2
+
+ .. code-block:: cpp
+
+ reader.ReadPointAt(2);
+ liblas::Point const& p = reader.GetPoint();
+
+ .. note::
+ A `ReadPointAt` method call implies an individual seek in the file per
+ point read. Use ``liblas::Reader::Seek`` if you wish to read a run
+ of points starting at a specified location in the file.
+
+
+ .. warning::
+ If the file is a compressed LAS file, ReadPointAt is going to be much
+ slower than randomly reading through an uncompressed file. The `LASzip`_
+ compression as of LASzip 1.0.1 is sequential in nature, and asking for the
+ 2nd point in the file means decompressing both the 0th and 1st points.
+
+7. Seek to the 10th point to start reading. A ``liblas::Reader`` provides a
+ `Seek` method to allow you to start reading from a specified location for
+ however many points you wish. This functionality is useful for reading
+ strips out of files.
+
+
+ .. code-block:: cpp
+
+ reader.Seek(10);
+ while (reader.ReadNextPoint())
+ ...
+
+==============================================================================
+Writing using ``liblas::Writer``
+==============================================================================
1. Include required header files from libLAS and C++ Standard Library
-.. code-block:: cpp
+ .. code-block:: cpp
- #include <liblas/laspoint.hpp>
- #include <liblas/laswriter.hpp>
- #include <fstream> // std::ifstream
- #include <iostream> // std::cout
+ #include <liblas/liblas.hpp>
+
+ #include <fstream> // std::ofstream
+ #include <iostream> // std::cout
2. Create output stream and associate it with .las file opened to write data
in **binary** mode
-.. code-block:: cpp
+ .. code-block:: cpp
- std::ofstream ofs;
- ofs.open("file.las", ios::out | ios::binary);
+ std::ofstream ofs;
+ ofs.open("file.las", ios::out | ios::binary);
+
+ .. note::
+ It is also possible to open the stream in append mode to add data
+ to an existing file. You should first instantiate a ``liblas::Reader``
+ and fetch the ``liblas::Header`` from the file, and then create the
+ ``liblas::Writer`` with that header and the ofstream opened in append
+ mode.
+
+ .. code-block:: cpp
-3. Create instance of Header class to define Public Header Block and set some values
+ liblas::Header header = reader.GetHeader();
-.. code-block:: cpp
+ std::ios::openmode m = std::ios::out | std::ios::in | std::ios::binary | std::ios::ate;
+ ofs.open("file.las", m);
+ liblas::Writer writer(ofs, header);
+
- liblas::Header header;
- header.SetDataFormatId(liblas::ePointFormat1);
- // fill other header members
+3. Create instance of ``liblas::Header`` class to define Public Header Block and set some values
+ .. code-block:: cpp
+ liblas::Header header;
+ header.SetDataFormatId(liblas::ePointFormat1); // Time only
+
+ // Set coordinate system using GDAL support
+ liblas::SpatialReference srs;
+ srs.SetFromUserInput("EPSG:4326");
+
+ header.SetSRS(srs);
+
+ // fill other header members
-.. note::
- The default constructed header object can be used as perfectly valid
- header. It will define LAS file according to LAS 1.2 and Point Data Format
- 0.
+
+ .. note::
+ Simply setting ``header.SetCompressed(true)`` on the header will be
+ sufficient to output a compressed file when the ``liblas::Writer`` is
+ created if `LASzip`_ support is enabled in libLAS, but it is up to the
+ user to specify the proper file name extension, `.laz`, when writing the
+ file.
+
+ .. note::
+ The default constructed header object can be used as perfectly valid
+ header. It will define LAS file according to LAS 1.2 and Point Data Format
+ 3.
4. Create LAS file writer object attached to the output stream and the based
on the header object.
-.. code-block:: cpp
+ .. code-block:: cpp
- liblas::Writer writer(ofs, header);
- // here the header has been serialized to disk into the *file.las*
+ liblas::Writer writer(ofs, header);
+ // here the header has been serialized to disk into the *file.las*
-5. Now, you can write some point records
+5. Write some point records
-.. code-block:: cpp
+ .. code-block:: cpp
- liblas::Point point;
- point.SetCoordinates(10, 20, 30);
- // fill other properties of point record
+ liblas::Point point;
+ point.SetCoordinates(10, 20, 30);
+ // fill other properties of point record
- writer.WritePoint(point);
+ writer.WritePoint(point);
-Here, one point is written to the *file.las*.
-=============================================
-Copying .las file
-=============================================
+
+==============================================================================
+Copying an .las file
+==============================================================================
Below, two simple examples present how to rewrite content from one LAS file to
another, in two different ways.
@@ -167,7 +244,7 @@
The library provides two `iterators <http://en.wikipedia.org/wiki/Iterator>`__
compatible with `iterator concept
<http://www.sgi.com/tech/stl/Iterators.html>`__ defined in `C++ Standard
-Template Library <http://en.wikipedia.org/wiki/C%2B%2B_standard_library>`_:_
+Template Library <http://en.wikipedia.org/wiki/C%2B%2B_standard_library>`__.
* lasreader_iterator - (`input iterator
<http://www.sgi.com/tech/stl/InputIterator.html>`__) used to read data from
@@ -178,36 +255,79 @@
.. code-block:: cpp
- #include <liblas/lasreader.hpp>
- #include <liblas/laswriter.hpp>
- #include <liblas/iterator.hpp>
- #include <algorithm>
- #include <exception>
- #include <iostream>
- using namespace liblas;
+ #include <liblas/liblas.hpp>
+ #include <algorithm>
+ #include <exception>
+ #include <iostream>
+
+ using namespace liblas;
More information about the Liblas-commits
mailing list