Rename and add doc.

doc/stages/readers.memoryview.rst

@@ -0,0 +1,54 @@
+.. _readers.memoryview:
+
+readers.memoryview
+==================
+
+The MemoryView Reader is a special stage that allows
+the reading of point data arranged in rows directly from memory --
+each point needs to have dimension data arranged at a fixed offset
+from a base address of the point.
+Before each point is read, the MemoryViewReader calls a function that
+should return the point's base address, or a null pointer if there are no
+points to be read.
+
+Note that the memoryview reader does not currently work with columnar
+data (data where individual dimensions are packed into arrays).
+
+Usage
+=====
+
+The MemoryViewReader cannot be used from the command-line.  It is for use
+by software using the PDAL API.
+
+After creating an instance of the MemoryViewReader, the user should
+call pushField() for every dimension that should be read from memory.
+pushField() takes a single argument, a MemoryViewReader::Field, that consists
+of a dimension name, a type and an offset from the base pointer:
+
+.. code-block:: c++
+
+    struct Field
+    {
+        std::string m_name;
+        Dimension::Type m_type;
+        size_t m_offset;
+    };
+
+    void pushField(const Field&);
+
+The user should also call setIncrementer(), a function that takes a
+single argument, an std::function that receives the ID of the point to
+be added and should return the base address of the point data, or a
+null pointer if there are no more points to be read.
+
+.. code-block:: c++
+
+    using PointIncrementer = std::function<char *(PointId)>;
+
+    void setIncrementer(PointIncrementer inc);
+
+
+Options
+-------
+
+None.

doc/stages/readers.rst

@@ -27,6 +27,7 @@ like :ref:`readers.oci`, or a network service like :ref:`readers.ept`.
    readers.ilvis2
    readers.las
    readers.matlab
+   readers.memoryview
    readers.mbio
    readers.mrsid
    readers.nitf
@@ -91,6 +92,10 @@ like :ref:`readers.oci`, or a network service like :ref:`readers.ept`.
 :ref:`readers.mbio`
     Read sonar bathymetry data from formats supported by the MB-System library.
 
+:ref:`readers.memoryview`
+    Read data from memory where dimension data is arranged in rows.  For
+    use only with the PDAL API.
+
 :ref:`readers.mrsid`
     Read data compressed by the MrSID 4.0 LiDAR Compressor. Requires the
     LizardTech Lidar_DSDK.

io/MemoryReader.cpp → io/MemoryViewReader.cpp

@@ -32,30 +32,30 @@
 * OF SUCH DAMAGE.
 ****************************************************************************/
 
-#include "MemoryReader.hpp"
+#include "MemoryViewReader.hpp"
 
 namespace pdal
 {
 
 static StaticPluginInfo const s_info
 {
     "readers.memoryview",
-    "Memory Reader",
+    "Memory View Reader",
     "http://pdal.io/stages/readers.memoryview.html",
     {}
 };
 
-CREATE_STATIC_STAGE(MemoryReader, s_info)
+CREATE_STATIC_STAGE(MemoryViewReader, s_info)
 
-std::string MemoryReader::getName() const { return s_info.name; }
+std::string MemoryViewReader::getName() const { return s_info.name; }
 
-MemoryReader::MemoryReader() : m_prepared(false)
+MemoryViewReader::MemoryViewReader() : m_prepared(false)
 {}
 
 
 // NOTE: - Forces reading of the entire file.
 /**
-QuickInfo MemoryReader::inspect()
+QuickInfo MemoryViewReader::inspect()
 {
     QuickInfo qi;
     FixedPointTable t(100);
@@ -90,10 +90,10 @@ QuickInfo MemoryReader::inspect()
 **/
 
 
-void MemoryReader::pushField(const Field& f)
+void MemoryViewReader::pushField(const Field& f)
 {
     if (m_prepared)
-        throwError("Can't pushField() after MemoryReader is prepared.");
+        throwError("Can't pushField() after MemoryViewReader is prepared.");
 
     for (auto& tempField : m_fields)
         if (tempField.m_name == f.m_name)
@@ -104,7 +104,7 @@ void MemoryReader::pushField(const Field& f)
 }
 
 
-void MemoryReader::addDimensions(PointLayoutPtr layout)
+void MemoryViewReader::addDimensions(PointLayoutPtr layout)
 {
     for (auto& f : m_fields)
     {
@@ -116,13 +116,13 @@ void MemoryReader::addDimensions(PointLayoutPtr layout)
 }
 
 
-void MemoryReader::initialize()
+void MemoryViewReader::initialize()
 {
     m_prepared = false;
 }
 
 
-void MemoryReader::prepared(PointTableRef)
+void MemoryViewReader::prepared(PointTableRef)
 {
     int xyz = 0;
     for (const FullField& f : m_fields)
@@ -169,15 +169,15 @@ void MemoryReader::prepared(PointTableRef)
 }
 
 
-void MemoryReader::ready(PointTableRef)
+void MemoryViewReader::ready(PointTableRef)
 {
     if (!m_incrementer)
         throwError("Points cannot be read without calling setIncrementer().");
     m_index = 0;
 }
 
 
-point_count_t MemoryReader::read(PointViewPtr v, point_count_t numPts)
+point_count_t MemoryViewReader::read(PointViewPtr v, point_count_t numPts)
 {
     PointId idx = v->size();
     point_count_t cnt = 0;
@@ -195,7 +195,7 @@ point_count_t MemoryReader::read(PointViewPtr v, point_count_t numPts)
 }
 
 
-bool MemoryReader::processOne(PointRef& point)
+bool MemoryViewReader::processOne(PointRef& point)
 {
     char *base = m_incrementer(m_index);
     if (!base)

io/MemoryReader.hpp → io/MemoryViewReader.hpp

@@ -44,7 +44,7 @@
 namespace pdal
 {
 
-class PDAL_DLL MemoryReader : public Reader, public Streamable
+class PDAL_DLL MemoryViewReader : public Reader, public Streamable
 {
 public:
     enum class Order
@@ -111,7 +111,7 @@ class PDAL_DLL MemoryReader : public Reader, public Streamable
 public:
     std::string getName() const;
 
-    MemoryReader();
+    MemoryViewReader();
 
     /**
       Push a data field into the structure of ordered fields.
@@ -124,7 +124,7 @@ class PDAL_DLL MemoryReader : public Reader, public Streamable
       Set a function that handles modifying the memory location of
       subsequent points.
       
-      \param inc  A function that is called by MemoryReader with the
+      \param inc  A function that is called by MemoryViewReader with the
         current point ID.  The function should return the base pointer
         of the point, or nullptr if there are no more points to read.
     */
@@ -161,7 +161,7 @@ class PDAL_DLL MemoryReader : public Reader, public Streamable
     virtual void prepared(PointTableRef);
 
     /**
-      Make MemoryReader ready for reading.
+      Make MemoryViewReader ready for reading.
     */
     virtual void ready(PointTableRef);
 
@@ -197,32 +197,34 @@ class PDAL_DLL MemoryReader : public Reader, public Streamable
     size_t m_zDiv;
 };
 
-inline std::istream& operator>>(std::istream& in, MemoryReader::Order& order)
+inline std::istream& operator>>(std::istream& in,
+    MemoryViewReader::Order& order)
 {
     std::string s(std::istreambuf_iterator<char>(in), {});
 
     s = Utils::toupper(s);
     if (s == "ROW")
-        order = MemoryReader::Order::RowMajor;
+        order = MemoryViewReader::Order::RowMajor;
     else if (s == "COLUMN")
-        order = MemoryReader::Order::ColumnMajor;
+        order = MemoryViewReader::Order::ColumnMajor;
     else
         throw pdal_error("Invalid value for option 'order'.  Must be 'row'"
             " or 'column'.");
     return in;
 }
 
 inline std::ostream& operator<<(std::ostream& out,
-    const MemoryReader::Order& order)
+    const MemoryViewReader::Order& order)
 {
-    if (order == MemoryReader::Order::RowMajor)
+    if (order == MemoryViewReader::Order::RowMajor)
         out << "row";
     else
         out << "column";
     return out;
 }
 
-inline std::istream& operator>>(std::istream& in, MemoryReader::Shape& shape)
+inline std::istream& operator>>(std::istream& in,
+    MemoryViewReader::Shape& shape)
 {
     std::string s(std::istreambuf_iterator<char>(in), {});
     StringList values = Utils::split2(s, ',');
@@ -250,7 +252,7 @@ inline std::istream& operator>>(std::istream& in, MemoryReader::Shape& shape)
 }
 
 inline std::ostream& operator<<(std::ostream& out,
-    const MemoryReader::Shape& shape)
+    const MemoryViewReader::Shape& shape)
 {
     out << shape.depth() << ", " << shape.rows() << ", " << shape.columns();
     return out;