Add reading streamer example

doc/development/writing-reader.rst

@@ -214,3 +214,10 @@ except in a CSV style format, and with the Z values scaled by .001.
 
 .. _`pipeline-myreader.json`: https://github.com/PDAL/PDAL/blob/master/examples/writing-reader/pipeline-myreader.json?raw=true
 .. _`test-reader-input.txt`: https://github.com/PDAL/PDAL/blob/master/examples/writing-reader/test-reader-input.txt?raw=true
+
+Streaming Reader
+-------------------------------------------------------------------------------
+
+PDAL's reader interface does not offer access to streaming points from a cloud.
+This can be accomplished via creating a custom writer class that can query the
+reader. An example is in ``examples/reading-streamer``.

examples/reading-streamer/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.6)
+project(StreamerTutorial)
+
+find_package(PDAL 2.0.0 REQUIRED CONFIG)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_executable(reading_streamer reading_streamer.cpp)
+
+target_link_libraries(reading_streamer PRIVATE ${PDAL_LIBRARIES})
+target_include_directories(reading_streamer PRIVATE
+    ${PDAL_INCLUDE_DIRS}
+    ${PDAL_INCLUDE_DIRS}/pdal)
+

examples/reading-streamer/reading_streamer.cpp

@@ -0,0 +1,95 @@
+#include <io/LasReader.hpp>
+#include <pdal/Writer.hpp>
+#include <pdal/Streamable.hpp>
+#include <pdal/PointView.hpp>
+#include <pdal/util/ProgramArgs.hpp>
+
+#include <iostream>
+
+namespace pdal
+{
+
+// A class to read a point cloud from a file point by point, without
+// loading it fully in memory. The points are printed to the screen,
+// but this can be replaced with any other processing.
+
+class PDAL_DLL StreamProcessor: public Writer, public Streamable
+{
+
+public:
+    std::string getName() const;
+    StreamProcessor();
+    ~StreamProcessor();
+
+private:
+
+    virtual void addArgs(ProgramArgs& args);
+    virtual void initialize();
+    virtual void writeView(const PointViewPtr view);
+    virtual bool processOne(PointRef& point);
+
+    StreamProcessor& operator=(const StreamProcessor&) = delete;
+    StreamProcessor(const StreamProcessor&) = delete;
+    StreamProcessor(const StreamProcessor&&) = delete;
+};
+
+std::string StreamProcessor::getName() const { return "sample streamer"; }
+
+StreamProcessor::StreamProcessor() {}
+
+StreamProcessor::~StreamProcessor() {}
+
+void StreamProcessor::addArgs(ProgramArgs& args)
+{
+}
+
+void StreamProcessor::initialize()
+{
+}
+
+// This will be called for each point in the cloud.
+bool StreamProcessor::processOne(PointRef& point)
+{
+   // Print the point coordinates
+   std::cout << "Process point: " 
+             << point.getFieldAs<double>(Dimension::Id::X) <<  ", " 
+             << point.getFieldAs<double>(Dimension::Id::Y) << ", " 
+             << point.getFieldAs<double>(Dimension::Id::Z) << std::endl;
+    return true;  
+}
+
+void StreamProcessor::writeView(const PointViewPtr view)
+{
+    throw pdal_error("The writeView() function must not be called in streaming mode.");
+}
+
+} // namespace pdal
+
+int main(int argc, char* argv[])
+{
+
+    using namespace pdal;
+
+    // Set the input point cloud    
+    Options read_options;
+    read_options.add("filename", "input.las");
+    LasReader reader;
+    reader.setOptions(read_options);
+
+    // buf_size is the number of points that will be
+    // processed and kept in this table at the same time. 
+    // A somewhat bigger value may result in some efficiencies.
+    int buf_size = 100;
+    FixedPointTable t(buf_size);
+    reader.prepare(t);
+
+    // Read each point and print it to the screen
+    StreamProcessor writer;
+    Options write_options;
+    writer.setOptions(write_options);
+    writer.setInput(reader);
+    writer.prepare(t);
+    writer.execute(t);
+
+    return 0;
+}

examples/writing-streamer/CMakeLists.txt

@@ -5,10 +5,10 @@ find_package(PDAL 2.0.0 REQUIRED CONFIG)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-add_executable(streamer_tutorial streamer_tutorial.cpp)
+add_executable(writing_streamer writing_streamer.cpp)
 
-target_link_libraries(streamer_tutorial PRIVATE ${PDAL_LIBRARIES})
-target_include_directories(streamer_tutorial PRIVATE
+target_link_libraries(writing_streamer PRIVATE ${PDAL_LIBRARIES})
+target_include_directories(writing_streamer PRIVATE
     ${PDAL_INCLUDE_DIRS}
     ${PDAL_INCLUDE_DIRS}/pdal)