PointContext -> PointContextRef

doc/tutorial/overview.rst

@@ -56,17 +56,18 @@ register their use of an existing dimension or may have PDAL create a dimension
 with a name and type as requested.  Dimensions are referenced using items in the
 enumeration Dimension::Id::Enum.
 
-PointContext
+Point Context
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PDAL stores points in what is called a point context (PointContext object).  All
 points in a single point context have the same dimensions and all operations on
 a PDAL pipeline make use of a single point context.  In addition to storing
 points, a point context also stores pipeline metadata that may get created as
-pipeline stages are executed.  A point context is a lightweight object that can
-be treated as a built-in type or POD.
+pipeline stages are executed.  Most functions receive a PointContextRef object,
+which refers to the active point context.  A PointContextRef can be stored
+or copied cheaply.
 
-PointBuffer
+Point Buffer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A point buffer (PointBuffer object) stores references to points.  All storage
@@ -166,7 +167,7 @@ pipeline.
     should occur at this time.  Initialization that can be deferred until the
     execution stage should be performed in the ready() method (see below).
 
-3) void addDimensions(PointContext ctx)
+3) void addDimensions(PointContextRef ctx)
 
     This method allows stages to inform a point context of the dimensions that
     it would like as part of the record of each point.  Normally, only readers
@@ -186,7 +187,7 @@ private virtual methods.  It is important to note that ready() and done() are
 called only once for each stage while run() is called once for each point buffer
 to be processed by the stage.
 
-1) void ready(PointContext ctx)
+1) void ready(PointContextRef ctx)
 
     This function allows preprocessing to be performed prior to actual
     processing of the points in a point buffer.  For example, filters may
@@ -204,7 +205,7 @@ to be processed by the stage.
     buffers.  This method is called once for each point buffer passed to the
     stage.
 
-3) void done(PointContext ctx)
+3) void done(PointContextRef ctx)
 
     This function allows a stage to clean up resources not released by a
     stage’s destructor.  It also allows other termination functions, such
@@ -233,7 +234,7 @@ the dimensions X, Y and Z.
 
     ::
 
-        void Reader::addDimensions(PointContext ctx)
+        void Reader::addDimensions(PointContextRef ctx)
         {
            ctx.registerDim(Dimension::Id::X);   
            ctx.registerDim(Dimension::Id::Y);
@@ -246,7 +247,7 @@ precision floating point.
 
 ::
 
-    void Reader::addDimensions(PointContext ctx)
+    void Reader::addDimensions(PointContextRef ctx)
     {
         FileHeader header;
 
@@ -393,16 +394,20 @@ Implementing a Writer:
 ................................................................................
 
 Analogous to the filter() method in a filter is the write() method of a writer.
-This function is usually the appropriate function to override when implementing
-a writer -- it would be unusual to need to implement run() for a writer.  A
+This function is usually the appropriate one to override when implementing
+a writer -- it would be unusual to need to implement run().  A
 typical writer will open its output file when ready() is called, write
-individual points in write() and close the file in done().  Important to note is
-that a writer may be passed multiple point buffers for output.  When
-implementing a writer, one should handle multiple calls to write() when
-possible.  If a write() function can’t provide correct output when called more
-than once, users of the writer should be warned to add a merge filter in the
-pipeline immediately before the writer.
-
+individual points in write() and close the file in done().
+
+Like a filter, a writer may receive multiple point buffers during processing
+of a pipeline.  This will result in the write() function being called once
+for each of the input point buffers.  Some current writers do not produce
+correct output when provided with multiple point buffers.  Users should
+be warned use a merge filter immediately prior to such writers to avoid
+errors.  As new writers are created, developers should try to make sure
+that they behave reasonably if passed multiple point buffers -- they
+correctly handle write() being called multiple times between after a single
+call to ready().
 
 ::
 

include/pdal/PDALUtils.hpp

@@ -87,7 +87,7 @@ inline ptree toPTree(MetadataNode const& node)
 }
 
 
-inline ptree toPTree(const PointContext& ctx)
+inline ptree toPTree(PointContextRef ctx)
 {
     ptree tree;
     ptree dimsTree;

include/pdal/PipelineManager.hpp

@@ -79,7 +79,7 @@ class PDAL_DLL PipelineManager
         { return m_pbSet; }
 
     // Get the point context;
-    PointContext context() const
+    PointContextRef context() const
         { return m_context; }
 
     MetadataNode getMetadata() const;

include/pdal/PointBuffer.hpp

@@ -58,7 +58,7 @@ class PDAL_DLL PointBuffer
     friend class plang::BufferedInvocation;
 public:
     PointBuffer();
-    PointBuffer(PointContext context) : m_context(context)
+    PointBuffer(PointContextRef context) : m_context(context)
     {}
 
     point_count_t size() const
@@ -161,7 +161,7 @@ class PDAL_DLL PointBuffer
         { return m_context.dims(); }
 
 protected:
-    PointContext m_context;
+    PointContextRef m_context;
     std::vector<PointId> m_index;
 
 private:

include/pdal/PointContext.hpp

@@ -270,6 +270,8 @@ class PointContext
         }
     }
 };
+// A point context is in some instances more easily understood as a reference.
+typedef PointContext PointContextRef;
 
 } //namespace
 

include/pdal/Stage.hpp

@@ -54,11 +54,6 @@ class StageRandomIterator;
 class StageBlockIterator;
 class StageRunner;
 class StageTester;
-//
-// supported options:
-//   <bool>debug
-//   <uint32>verbose
-//
 
 class PDAL_DLL Stage
 {
@@ -75,8 +70,8 @@ class PDAL_DLL Stage
     void setInput(Stage *input)
         { m_inputs.push_back(input); }
 
-    void prepare(PointContext ctx);
-    PointBufferSet execute(PointContext ctx);
+    void prepare(PointContextRef ctx);
+    PointBufferSet execute(PointContextRef ctx);
 
     void setSpatialReference(SpatialReference const&);
     const SpatialReference& getSpatialReference() const;
@@ -104,7 +99,7 @@ class PDAL_DLL Stage
         { return Dimension::IdList(); }
     static std::string s_getInfoLink()
         { return std::string(); }
-    virtual boost::property_tree::ptree toPTree(PointContext ctx) const 
+    virtual boost::property_tree::ptree toPTree(PointContextRef ctx) const 
         { return boost::property_tree::ptree(); }
 
 #define SET_STAGE_NAME(name, description)  \
@@ -149,15 +144,15 @@ class PDAL_DLL Stage
         {}
     virtual void writerProcessOptions(const Options& /*options*/)
         {}
-    void l_initialize(PointContext ctx);
-    void l_done(PointContext ctx);
+    void l_initialize(PointContextRef ctx);
+    void l_done(PointContextRef ctx);
     virtual void initialize()
         {}
-    virtual void addDimensions(PointContext ctx)
+    virtual void addDimensions(PointContextRef ctx)
         { (void)ctx; }
-    virtual void ready(PointContext ctx)
+    virtual void ready(PointContextRef ctx)
         { (void)ctx; }
-    virtual void done(PointContext ctx)
+    virtual void done(PointContextRef ctx)
         { (void)ctx; }
     virtual PointBufferSet run(PointBufferPtr buffer)
     {

include/pdal/drivers/bpf/BpfReader.hpp

@@ -77,10 +77,10 @@ class PDAL_DLL BpfReader : public Reader
 
     virtual void processOptions(const Options& options);
     virtual void initialize();
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& buf, point_count_t num);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     virtual bool eof();
 
     bool readUlemData();

include/pdal/drivers/caris/CloudReader.hpp

@@ -106,11 +106,11 @@ class CloudReader : public pdal::Reader
 
 
     virtual void initialize();
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& buf, point_count_t num);
     virtual bool eof();
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
 
     void throwIfItrError() const;
 };

include/pdal/drivers/faux/Reader.hpp

@@ -110,8 +110,8 @@ class PDAL_DLL Reader : public pdal::Reader
     int m_returnNum;
 
     virtual void processOptions(const Options& options);
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx)
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx)
     {
         m_returnNum = 1;
         m_time = 0;

include/pdal/drivers/greyhound/Reader.hpp

@@ -78,8 +78,8 @@ class PDAL_DLL GreyhoundReader : public pdal::Reader
 
     virtual void initialize();
     virtual void processOptions(const Options& options);
-    virtual void addDimensions(PointContext pointContext);
-    virtual void ready(PointContext ctx);
+    virtual void addDimensions(PointContextRef pointContext);
+    virtual void ready(PointContextRef ctx);
 };
 
 namespace iterators

include/pdal/drivers/icebridge/Reader.hpp

@@ -71,10 +71,10 @@ class PDAL_DLL Reader : public pdal::Reader
     Hdf5Handler m_hdf5Handler;
     point_count_t m_index;
 
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& data, point_count_t count);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     virtual bool eof();
 
     Reader& operator=(const Reader&);   // Not implemented.

include/pdal/drivers/las/Reader.hpp

@@ -90,12 +90,12 @@ class PDAL_DLL Reader : public pdal::Reader
         { return StreamFactoryPtr(new FilenameStreamFactory(m_filename)); }
     virtual void initialize();
     virtual void initialize(MetadataNode& m);
-    virtual void addDimensions(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
     void extractMetadata(MetadataNode& m);
     virtual void processOptions(const Options& options);
-    virtual void ready(PointContext ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& buf, point_count_t count);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     virtual bool eof()
         { return m_index >= getNumPoints(); }
     void loadPoint(PointBuffer& data, char *buf, size_t bufsize);

include/pdal/drivers/las/Writer.hpp

@@ -111,9 +111,9 @@ class PDAL_DLL Writer : public pdal::Writer
     std::unique_ptr<ZipPoint> m_zipPoint;
 
     virtual void processOptions(const Options& options);
-    virtual void ready(PointContext ctx);
+    virtual void ready(PointContextRef ctx);
     virtual void write(const PointBuffer& pointBuffer);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     bool m_headerInitialized;
     bool m_discardHighReturnNumbers;
     boost::uint64_t m_streamOffset; // the first byte of the LAS file

include/pdal/drivers/nitf/Writer.hpp

@@ -60,7 +60,7 @@ class PDAL_DLL Writer : public las::Writer
 
 private:
     virtual void processOptions(const Options& options);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
 
     std::string m_filename;
     std::string m_cLevel;

include/pdal/drivers/oci/OciReader.hpp

@@ -42,8 +42,6 @@
 namespace pdal
 {
 
-class PointContext;
-
 namespace drivers
 {
 namespace oci
@@ -68,8 +66,8 @@ class PDAL_DLL OciReader : public pdal::Reader
 private:
     virtual void initialize();
     virtual void processOptions(const Options& options);
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx)
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx)
         { m_atEnd = false; }
     virtual point_count_t read(PointBuffer& buf, point_count_t);
     virtual bool eof()

include/pdal/drivers/oci/Writer.hpp

@@ -99,9 +99,9 @@ class PDAL_DLL Writer : public pdal::Writer
 
     virtual void processOptions(const Options& options);
     virtual void initialize();
-    virtual void ready(PointContext ctx);
+    virtual void ready(PointContextRef ctx);
     virtual void write(const PointBuffer& buffer);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     void writeInit();
     void writeTile(const PointBuffer& buffer);
 

include/pdal/drivers/oci/common.hpp

@@ -130,7 +130,7 @@ class Block
     Connection m_connection;
     sdo_pc* pc;
     int32_t m_num_remaining;
-    PointContext m_ctx;
+    PointContextRef m_ctx;
     schema::XMLSchema m_schema;
     size_t m_point_size;
     bool m_fetched;  // Set when fetched but not initialized

include/pdal/drivers/p2g/P2gWriter.hpp

@@ -86,9 +86,9 @@ class PDAL_DLL P2gWriter : public pdal::Writer
     P2gWriter& operator=(const P2gWriter&); // not implemented
 
     virtual void processOptions(const Options& options);
-    virtual void ready(PointContext ctx) {};
+    virtual void ready(PointContextRef ctx) {};
     virtual void write(const PointBuffer& buf);
-    virtual void done(PointContext ctx) {};
+    virtual void done(PointContextRef ctx) {};
     virtual void initialize() {};
 
     boost::scoped_ptr<OutCoreInterp> m_interpolator;

include/pdal/drivers/pcd/Reader.hpp

@@ -60,8 +60,8 @@ class PDAL_DLL PcdReader : public pdal::Reader
 private:
     point_count_t m_numPts;
 
-    virtual void addDimensions(PointContext ctx);
-    virtual void ready(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& buf, point_count_t count);
 };
 

include/pdal/drivers/pcd/Writer.hpp

@@ -61,7 +61,7 @@ class PDAL_DLL PcdWriter : public pdal::Writer
 
 private:
     virtual void processOptions(const Options&);
-    virtual void ready(PointContext ctx) {};
+    virtual void ready(PointContextRef ctx) {};
     virtual void write(const PointBuffer& buf);
 
     std::string m_filename;

include/pdal/drivers/pgpointcloud/PgReader.hpp

@@ -106,11 +106,11 @@ class PDAL_DLL PgReader : public pdal::Reader
     void getSession() const;
 
 private:
-    virtual void addDimensions(PointContext ctx);
+    virtual void addDimensions(PointContextRef ctx);
     virtual void processOptions(const Options& options);
-    virtual void ready(PointContext ctx);
+    virtual void ready(PointContextRef ctx);
     virtual point_count_t read(PointBuffer& buf, point_count_t count);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     virtual bool eof()
         { return m_atEnd; }
 

include/pdal/drivers/pgpointcloud/Writer.hpp

@@ -68,9 +68,9 @@ class PDAL_DLL Writer : public pdal::Writer
     Writer(const Writer&); // not implemented
 
     virtual void processOptions(const Options& options);
-    virtual void ready(PointContext ctx);
+    virtual void ready(PointContextRef ctx);
     virtual void write(const PointBuffer& pointBuffer);
-    virtual void done(PointContext ctx);
+    virtual void done(PointContextRef ctx);
     virtual void initialize();
 
     void writeInit();