PointCloud2.H

Go to the documentation of this file.

/*! @file
    @author Shane Grant
    @copyright GNU Public License (GPL v3)
    @section License
    @verbatim
    // ////////////////////////////////////////////////////////////////////////
    //              The iLab Neuromorphic Robotics Toolkit (NRT)             //
    // Copyright 2010-2012 by the University of Southern California (USC)    //
    //                          and the iLab at USC.                         //
    //                                                                       //
    //                iLab - University of Southern California               //
    //                Hedco Neurociences Building, Room HNB-10               //
    //                    Los Angeles, Ca 90089-2520 - USA                   //
    //                                                                       //
    //      See http://ilab.usc.edu for information about this project.      //
    // ////////////////////////////////////////////////////////////////////////
    // This file is part of The iLab Neuromorphic Robotics Toolkit.          //
    //                                                                       //
    // The iLab Neuromorphic Robotics Toolkit is free software: you can      //
    // redistribute it and/or modify it under the terms of the GNU General   //
    // Public License as published by the Free Software Foundation, either   //
    // version 3 of the License, or (at your option) any later version.      //
    //                                                                       //
    // The iLab Neuromorphic Robotics Toolkit is distributed in the hope     //
    // that it will be useful, but WITHOUT ANY WARRANTY; without even the    //
    // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR       //
    // PURPOSE.  See the GNU General Public License for more details.        //
    //                                                                       //
    // You should have received a copy of the GNU General Public License     //
    // along with The iLab Neuromorphic Robotics Toolkit.  If not, see       //
    // <http://www.gnu.org/licenses/>.                                       //
    // ////////////////////////////////////////////////////////////////////////
    @endverbatim */

#ifndef INCLUDE_NRT_POINTCLOUD2_POINTCLOUD2_H
#define INCLUDE_NRT_POINTCLOUD2_POINTCLOUD2_H

#include <nrt/config.h>
#ifdef NRT_HAVE_CLOUD

#include <type_traits>
#include <memory>
#include <nrt/PointCloud2/details/DenseData.H>
#include <nrt/PointCloud2/details/SparseData.H>
#include <nrt/PointCloud2/details/LookupCache.H>
#include <nrt/PointCloud2/PointCloud2Data.H>
#include <nrt/PointCloud2/Common/Indices.H>

#include <nrt/Core/Design/IteratorRange.H>

#include <nrt/External/cereal/types/memory.hpp>

namespace nrt
{
  //! A class for representing point clouds
  /*! PointClouds are collections of data associated with
      geometrically defined points.  This class allows for
      arbitrary data to be associated with a point cloud
      in addition to the basic geometry.

      A CMAKE compilation flag, POINTCLOUD_DOUBLE, determines whether
      the base type of the point cloud will use single or double
      precision floating point numbers for the geometry.  The
      geometry fields will define a three dimensional homogenous point
      (XYZ + W) that is the core of a pointcloud.

      Additional fields can be added onto a point cloud allowing
      each geometrical point to be associated with additional data.
      These fields can be dense or sparse but will always be tied
      to an existing geometrical point in the point cloud.  Point
      clouds cannot store information that does not directly
      relate to their geometry.

      Dense fields will have a 1:1 correspondence with geometry
      while sparse fields do not need to obey this; you are allowed
      to have a geometrical entry without having an associated
      sparse entry.

      Sparse fields are denoted as sparse when they are created
      by wrapping a type in the SparseField<> template,
      but apart from that point operate without the need for
      an explicit demarcation.  Point clouds have the restriction
      that any field added, regardless of whether it is dense or
      sparse, must be unique when judged on an std::is_same
      basis.

      In general sparse data will be slower to access or insert
      and should only be used when the tradeoff between size and
      decreased performance makes sense.

      It should be noted that regardless of the data type accessed
      in a Point Cloud, if it is specified as a specific dense
      or sparse field as a template parameter, there is a small
      cost associated with an implementation specific lookup that
      must occur.  This means that code that relies on calling
      functionality that specifies explicit fields should be be
      avoided in loops if possible.  For example, the creation of
      iterator objects incurs this lookup cost, but the actual use
      of iterators does not - thus for maximum performance if the
      size/order of a point cloud will not change during iteration,
      it is best to avoid calculating end iterators at each
      iteration.  The cost of this lookup is small in isolation, but
      used incorrectly in looping situations can result in degraded
      performance.

      PointClouds are reference counted and utilize a copy-on-write
      mechanism similar to nrt::Array.  This means that any
      function of PointCloud2 that can modify its contents in any fashion
      may perform a deep copy to obtain unique ownership of the underlying
      data.  Constant accessors will never perform a deep copy.  If you
      are the sole owner of the data, a deep copy will not occur.

      Since PointClouds use reference counting to manage their memory, you
      should follow sensible conventions in multi-threaded environments
      regarding passing by value or by reference: if it is not known whether
      a stable reference to a cloud exists, pass by value: it will increment
      the reference count and keep the memory safe until it has been used.
      Otherwise, if it is known that a stable reference to a cloud will exist
      throughout the lifetime of a function where it has been passed by reference,
      then there is no need to pass by value.  Passing by value incurs a slightly
      higher overhead due to an atomic lookup that must occur.  This information
      only applies to clouds that are passed as const.  Non const clouds will
      always incur a deep copy as soon as they are modified.

      @ingroup pointcloud
      */
  class PointCloud2
  {
    public:
      /*! @anchor PointCloud2TypedefsGroup
          @name Convenience typedefs
          The following typedefs allow easy access of related structures
          that depend upon the point cloud base type */
      //! @{
      //! The base type for a point cloud, determined by a CMAKE compilation flag
      typedef POINTCLOUD2_BASE_TYPE BaseType;

      //! The type of the underlying geometry
      typedef PointSSE<POINTCLOUD2_BASE_TYPE> Geometry;

      //! A 3x1 vector
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, 3, 1> Vector3;
      //! A 4x1 vector
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, 4, 1> Vector4;
      //! An Nx1 vector
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, Eigen::Dynamic, 1> VectorX;

      //! A 3x3 matrix
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, 3, 3> Matrix3;
      //! A 4x4 matrix
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, 4, 4> Matrix4;
      //! An NxN matrix
      typedef Eigen::Matrix<POINTCLOUD2_BASE_TYPE, Eigen::Dynamic, Eigen::Dynamic> MatrixX;

      //! An affine transformation matrix
      typedef Eigen::Transform<POINTCLOUD2_BASE_TYPE, 3, Eigen::Affine> AffineTransform;
      //! @}

      /*! @name Constructors and assignment operators
          @anchor PointCloud2ConstructorGroup */
      //! @{

      //! Create an empty point cloud with no fields
      /*! The created point cloud will have geometrical data
          (as all point clouds do), but no additional dense
          or sparse fields
          @param initialSize The initial size for the point cloud.  Note that any
                             geometry allocated here will be completely zero valued
                             and thus not a valid homogenous point.  It is best to
                             consider the data as allocated but un-initialized. */
      PointCloud2( size_t initialSize = 0);

      //! @}

      //! Create an empty point cloud with a set of fields
      /*! This adds fields to the point cloud, giving it
          the capability of storing various data types.
          Data types must be distinct from an std::is_same
          basis regardless of whether they are dense or sparse.

          Data types are assumed to be dense by default and can
          be marked as sparse by wrapping in the template class
          SparseField<>.  Fields marked as sparse only need
          to be marked as sparse during insertion and can
          be utilized without the SparseField<> template
          wrapper in all other functions.

          Sparse fields will only store data for indicies that
          have been initialized with some information.  Sparse
          fields are slower to access and should be used
          when the tradeoff between space and time makes sense.

          The point cloud will also, as all clouds do, contain
          geometrical data for each entry.

          @tparam Fields A set of fields to add
          @param initialSize The initial size for the point cloud.  Note that any
                             geometry or other fields allocated here will be completely
                             zero valued and thus likely not valid data.  It is best
                             to consider the data (including geometry) as allocated
                             but not initialized */
      template <class ... Fields>
      static PointCloud2 create( size_t initialSize = 0 );

      /*! @name Constructors and assignment operators */
      //! @{

      //! Create from an already existing cloud
      /*! This will create a shallow copy of the other cloud
          that will only become a deep copy upon modification
          or an explicit call to deepCopy() */
      PointCloud2( PointCloud2 const & other );

      //! Move from an already existing cloud
      /*! This will move the data from another cloud into this one
          and cause the other cloud to become invalid.  Using an
          invalid cloud will result in undefined behavior */
      PointCloud2( PointCloud2 && other );

      //! Destructor
      ~PointCloud2();

      //! Assignment operator
      /*! This will create a shallow copy of the other cloud
          that will only become a deep copy upon modification
          or an explicit call to deepCopy() */
      PointCloud2 & operator=( PointCloud2 const & other );

      //! R value move assignment operator
      /*! This will result in the other point cloud being made
          invalid; using an invalid point cloud will result in
          undefined behavior */
      PointCloud2 & operator=( PointCloud2 && other );

      //! @}
      /*! @anchor PointCloud2FieldOperationsGroup
          @name Field operations
          Functionality concerned with inserting, deleting,
          or otherwise querying the dense or sparse fields
          of a point cloud. */
      //! @{

      //! Adds fields to this point cloud
      /*! This adds a field to the point cloud, giving it
          the capability of storing a particular data type.
          Data types must be distinct from an std::is_same
          basis regardless of whether they are dense or sparse.

          Data types are assumed to be dense by default and can
          be marked as sparse by wrapping in the template class
          SparseField<>.  Fields marked as sparse only need
          to be marked as sparse during insertion and can
          be utilized without the SparseField<> template
          wrapper in all other functions.

          Sparse fields will only store data for indicies that
          have been initialized with some information.  Sparse
          fields are slower to access and should be used
          when the tradeoff between space and time makes sense.

          Dense fields will be initialized with zero valued data
          which may be invalid depending on their type.

          If a field already exists, calling addField with it again
          will do nothing.

          @tparam Fields A set of fields to add */
      template <class ... Fields>
      void addField();

      //! Removes fields from the point cloud
      /*! Removing a field will delete all data associated with
          it in the point cloud.

          For sparse fields, there is no need to specify the
          type as sparse with SparseField<> as this will be
          automatically inferred for a sparse field.  If
          this is specified, it will be automatically stripped.

          @tparam Fields The fields to remove */
      template <class ... Fields>
      void removeField();

      //! Checks if the point cloud contains a specific field, dense or sparse
      /*! SparseField<> will be stripped if present and is
          not necessary.
          @tparam T The field type to check */
      template <class T>
      bool hasField() const;

      //! Checks if the point cloud contains a specific dense field
      template <class T>
      bool hasDenseField() const;

      //! Checks if the point cloud contains a specific sparse field
      /*! SparseField<> will be stripped if present and is
          not necessary.
          @tparam T The field type to check */
      template <class T>
      bool hasSparseField() const;

      //! Checks whether a specific index in the point cloud contains data of a particular sparse type
      /*! SparseField<> will be stripped if present and is not necessary
          @tparam T The field type to check
          @param index The index to check
          @return Whether the requested index contains the type of sparse data */
      template <class T>
      bool hasSparseData( size_t const index ) const;

      //! Assuming the requested field is sparse, retrieves all indices that contain the field
      /*! SparseField<> will be stripped if present and is not necessary
          @tparam T The field type to check
          @return All indices that contain the sparse data. */
      template <class T>
      Indices getSparseIndices() const;

      //! Checks if a point cloud has the same fields as another
      bool hasSameFields( PointCloud2 const other ) const;

      //! Gets the number of dense entries in the point cloud
      size_t size() const;

      //! Gets the number of entries for a particular field
      /*! SparseField<> will be stripped if present and is
          not necessary
          @tparam T The type to check the size of */
      template <class T>
      size_t size() const;

      //! Gets whether the cloud is completely empty (no dense entries)
      bool empty() const;

      //! @}

      //! @anchor PointCloud2ElementAccessGroup
      /*! @name Individual element access
          Functions to query individual elements from a point
          cloud.  In general, this will be slower than using
          iterators to access multiple elements */
      //! @{

      //! Returns a reference to the geometry at the specified index
      Geometry & operator[]( size_t index );

      //! Returns a const reference to the geometry at the specified index
      Geometry const & operator[]( size_t index ) const;

      //! Returns a reference to the geometry at the specified index
      /*! The data contained in the returned point will reference data
          stored in the cloud; modifying this structure will directly
          modify the data internal to the point cloud */
      PointCloud2DataRef<> get( size_t index );

      //! Returns a reference to fields at the requested index
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          Geometry is always included regardless of fields specified.

          @tparam Fields The fields to iterate over

          @throws PointCloud2FieldsException If at least one field does not exist in the cloud */
      template <class ... Fields>
      PointCloud2DataRef<typename StripSparse<Fields>::type...> get( size_t index );

      //! Returns a constant reference to the geometry at the specified index
      PointCloud2ConstDataRef<> at( size_t index ) const;

      //! Returns a constant reference to fields at the requested index
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          Geometry is always included regardless of fields specified.

          @tparam Fields The fields to iterate over

          @throws PointCloud2FieldsException If at least one field does not exist in the cloud */
      template <class ... Fields>
      PointCloud2ConstDataRef<typename StripSparse<Fields>::type...> at( size_t index ) const;

      //! @}

      //! An iterator for going over only geometry
      typedef Geometry * geometry_iterator;
      //! An iterator for going over only constant geometry
      typedef Geometry const * geometry_const_iterator;

      //! An iterator over geometry and other fields
      /*! Creating one of these iterators may cause a deep copy of the underlying data to occur if
          not the sole owner of the data.  When possible, constant iterators should be used as
          these do not incur a deep copy penalty

          Iterators will always include a reference to the geometry and this needs not be
          specified during their creation.

          Dereferencing an iterator works in a similar fashion to the get() and at() functions of
          PointCloud2 - this will return a PointCloud2DataRef that contains references to the
          actual data in the point cloud.  Modifying this PointCloud2DataRef will change the data
          in the point cloud directly.

          Iterators provide two additional functions, sparse(), which returns true if the iterator
          includes sparse data, and index(), which returns the index of the current value in
          the point cloud.  index() is especially useful if traversing over sparse data or a subset,
          since it gives a way to index back into the original point cloud.

          Also see: @ref IteratorBase for empty template instantiation and
          @ref IteratorVariadic for variadic instantiation. */
      template <class ... Fields> class Iterator;
      template <class ... Fields> friend class Iterator;

      //! A constant iterator over geometry and other fields
      /*! Constant iterators do not need to perform deep copies since they cannot modify the
          data.  Thus these will in general be much more efficient to use if multiple references
          to the underlying data exist.

          Iterators will always include a reference to the geometry and this needs not be
          specified during their creation.

          Dereferencing an iterator works in a similar fashion to the get() and at() functions of
          PointCloud2 - this will return a constant PointCloud2DataRef that contains references to the
          actual data in the point cloud.  Modifying this PointCloud2DataRef is not possible and data
          cannot be changed in the original point cloud.

          Iterators provide two additional functions, sparse(), which returns true if the iterator
          includes sparse data, and index(), which returns the index of the current value in
          the point cloud.  index() is especially useful if traversing over sparse data or a subset,
          since it gives a way to index back into the original point cloud.

          Also see: @ref ConstIteratorBase for empty template instantiation and
          @ref ConstIteratorVariadic for variadic instantiation. */
      template <class ... Fields> class ConstIterator;
      template <class ... Fields> friend class ConstIterator;

      //! @anchor PointCloud2IteratorsGroup
      /*! @name Iterators
          The following iterators provide efficient access to the contents of a point cloud */
      //! @{

      //! Get a basic iterator (includes geometry) to the beginning of the data
      /*! Will perform a deep copy if not the sole owner of underlying data */
      Iterator<> begin();

      //! Get a basic iterator (includes geometry) to the beginning of the data
      ConstIterator<> begin() const;

      //! Get a basic iterator (includes geometry) to the beginning of the data
      ConstIterator<> const_begin() const;

      //! Get an iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> begin();

      //! Get a constant iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> begin() const;

      //! Get a constant iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> const_begin() const;

      //! Get a basic iterator (includes geometry) to one past the end of the data
      /*! Will perform a deep copy if not the sole owner of underlying data. */
      Iterator<> end();

      //! Get a basic iterator (includes geometry) to one past the end of the data
      ConstIterator<> end() const;

      //! Get a basic iterator (includes geometry) to one past the end of the data
      ConstIterator<> const_end() const;

      //! Get an iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> end();

      //! Get a constant iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> end() const;

      //! Get a constant iterator to the requested fields, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if no valid sparse intersection can be found in the case
                                             when a sparse field is specified */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> const_end() const;

      //! Gets an iterator to only geometrical data (first entry)
      geometry_iterator geometry_begin();

      //! Gets an iterator to only geometrical data (first entry)
      geometry_const_iterator geometry_begin() const;

      //! Gets an iterator to only geometrical data (first entry)
      geometry_const_iterator geometry_const_begin() const;

      //! Gets an iterator to only geometrical data (past the last entry)
      geometry_iterator geometry_end();

      //! Gets an iterator to only geometrical data (past the last entry)
      geometry_const_iterator geometry_end() const;

      //! Gets an iterator to only geometrical data (past the last entry)
      geometry_const_iterator geometry_const_end() const;

      //! @}

      /*! @name Subset iterators
          The following subset iterators provide access to only specified indices
          of a point cloud */
      //! @{

      //! Get a basic iterator (includes geometry) to the beginning of the subset
      /*! Will perform a deep copy if not the sole owner of underlying data
          @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      Iterator<> subset_begin( Indices const indices );

      //! Get a basic iterator (includes geometry) to the beginning of the subset
      /*! @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      ConstIterator<> subset_begin( Indices const indices ) const;

      //! Get a basic iterator (includes geometry) to the beginning of the subset
      /*! @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      ConstIterator<> subset_const_begin( Indices const indices ) const;

      //! Get an iterator to the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_begin( Indices const indices );

      //! Get an constant iterator to the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_begin( Indices const indices ) const;

      //! Get an constant iterator to the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_const_begin( Indices const indices ) const;

      //! Get a basic iterator (includes geometry) to one past the end of the subset
      /*! Will perform a deep copy if not the sole owner of underlying data
          @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      Iterator<> subset_end( Indices const indices );

      //! Get a basic iterator (includes geometry) to one past the end of the subset
      /*! @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      ConstIterator<> subset_end( Indices const indices ) const;

      //! Get a basic iterator (includes geometry) to one past the end of the subset
      /*! @param indices The indices of the subset to iterate on
          @throws PointCloud2SubsetException if an empty set of indices is passed */
      ConstIterator<> subset_const_end( Indices const indices ) const;

      //! Get an iterator to one past the end of the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_end( Indices const indices );

      //! Get an constant iterator to one past the end of the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_end( Indices const indices ) const;

      //! Get an constant iterator to one past the end of the requested fields in a subset, including geometry
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Iterators with sparse fields
          will perform more slowly than those with dense only fields,
          especially during iterator creation.  Iterator traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the iterator.  Creation time will be
          longer than creating a dense iterator and scale with the size of the
          strictest subset and the number of fields to be iterated.

          @tparam T The first field requested to be iterated over
          @tparam OtherT The other fields requested to be iterated over.
          @param indices The indices of the subset to iterate on
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...> subset_const_end( Indices const indices ) const;

      //! @}

      //! @anchor PointCloud2RangesGroup
      /*! @name Ranges
          The following classes provide a lightweight range access to the contents of a point cloud

          Creating a range may cause a deep copy of the underlying data to occur if not the sole
          owner of the data while requesting a non constant range.  Ranges wrap up a begin and
          end iterator and give a convenient way to access point cloud data using mechanisms such
          as a range based for loop.

          Ranges will always include a reference to the geometry and this needs not be specified
          during their creation. */
      //! @{

      //! Gets a range that only includes raw geometry over the entire point cloud
      /*! Unlike regular ranges, a geometry_range will directly access geometry data
          and will not be wrapped in a PointCloud2DataRef<>.  This means that
          your iteration should look something like:

          @code
          for( PointCloud2::Geometry const & p : myCloud.geometry_range() )
            p.x() = p.y();
          @endcode

          Will perform a deep copy if not the owner of underlying data */
      IteratorRange<geometry_iterator> geometry_range();

      //! Gets a range that only includes raw constant geometry over the entire point cloud
      IteratorRange<geometry_const_iterator> geometry_range() const;

      //! Gets a range that only includes raw constant geometry over the entire point cloud
      IteratorRange<geometry_const_iterator> geometry_const_range() const;

      //! Gets a range that only includes geometry over the entire point cloud
      /*! Ranges will return PointCloud2DataRef<> r-values which contain references to
          point cloud data.  This means that data iterated over by a range is already by
          reference and can be modified directly:

          @code
          for( PointCloud2DataRef<> data : myCloud.range() ) // note the lack of & on data
            data.geometry().x() = 3.4f; // changes a value inside of the cloud
          @endcode

          Will perform a deep copy if not the sole owner of underlying data. */
      IteratorRange<Iterator<>> range();

      //! Gets a range that only includes constant geometry over the entire point cloud
      IteratorRange<ConstIterator<>> range() const;

      //! Gets a range that only includes constant geometry over the entire point cloud
      IteratorRange<ConstIterator<>> const_range() const;

      //! Gets a range that only includes geometry over a subset of the cloud
      /*! Will perform a deep copy if not the sole owner of underlying data. */
      IteratorRange<Iterator<>> subset_range( Indices const indices );

      //! Gets a range that only includes constant geometry over a subset of the cloud
      IteratorRange<ConstIterator<>> subset_range( Indices const indices ) const;

      //! Gets a range that only includes constant geometry over a subset of the cloud
      IteratorRange<ConstIterator<>> subset_const_range( Indices const indices ) const;

      //! Gets a range over the requested fields for the entire point cloud
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> range();

      //! Gets a range over the requested fields for the entire point cloud
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> range() const;

      //! Gets a range over the requested fields for the entire point cloud
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> const_range() const;

      //! Gets a range over the requested fields for some subset
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          Will perform a deep copy if not the sole owner of underlying data.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @param indices The indices of the subset to range over
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<Iterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> subset_range( Indices const indices );

      //! Gets a range over the requested fields for the entire point cloud
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @param indices The indices of the subset to range over
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> subset_range( Indices const indices ) const;

      //! Gets a range over the requested fields for the entire point cloud
      /*! If the requested fields do not exist inside of the point cloud,
          an exception will be thrown.  Ranges with sparse fields
          will perform more slowly than those with dense only fields,
          especially during range creation.  Range traversal time
          should be similar in both cases.

          Sparse fields do not (and should not) need to be explicitly specified as sparse
          using SparseField<>.  This will be stripped if present.

          If at least one requested field is sparse, the strictest intersection of the
          sparse indices will be iterated over by the range.  Creation time will be
          longer than creating a dense range and scale with the size of the
          strictest subset and the number of fields to be ranged over.

          @tparam T The first field requested in the range.
          @tparam OtherT The other fields requested in the range
          @param indices The indices of the subset to range over
          @throws PointCloud2FieldsException If at least one field does not exist in the cloud or
                                             if at least one sparse field is specified that does
                                             not have data for a provided index */
      template <class T, class ... OtherT>
      IteratorRange<ConstIterator<typename StripSparse<T>::type, typename StripSparse<OtherT>::type...>> subset_const_range( Indices const indices ) const;

      //! @}

      /*! @name Cloud insertion and deletion
          Functionality for inserting elements, resizing the point cloud, and
          clearing elements or the entire cloud */
      //! @{

      //! Resizes the point cloud
      /*! If the new size is greater than the old size, dense
          data will be created to fill the new indices.  The newly
          created dense data is not guaranteed to be valid.

          If the size causes a reduction in the size of the
          point cloud, any dense data exceeding the new size
          will be removed.  This will also cause any sparse data
          data associated with indices that no longer exist to be
          removed.  This removal of sparse data takes time linear
          in the difference of cloud size and logarithmic in the number
          of elements in a sparse field.

          @param size The new size for the point cloud */
      void resize( size_t size );

      //! Removes all data in every field (but does not remove fields) including geometry
      void clear();

      //! Inserts a single geometrical point at the end of the cloud
      /*! Any dense fields currently contained in the point cloud will be given
          zero valued data to correspond with the dense entry created by this insertion.
          Depending on the data type, this may result in invalid data for those dense
          fields.  It is suggested to fully specify all types in the cloud, if possible,
          when calling the templated version of insert to prevent any invalid data
          from existing. */
      void insert( Geometry const & geo );

      //! Inserts a single point at the end of the cloud
      /*! If any dense fields currently contained in the point cloud are not specified
          in the input data, they will be given zero valued data to correspond with
          the dense entry created by this insertion.  Depending on the data type,
          this may result in invalid data.  Therefor it is suggested to always fully
          specify dense types during an insertion if possible.

          @tparam Fields The fields to insert, which may include any fields (dense or
                         sparse) in the point cloud.  Sparse fields should not be
                         wrapped in SparseField<>.
          @throws PointCloud2FieldsException If any single field listed does not exist */
      template <class ... Fields>
      void insert( PointCloud2Data<Fields...> const & point );

      //! Adds sparse data to a point
      /*! This function adds sparse data entries to some point that was previously only
          associated with dense data.  The sparse fields must exist in the point cloud
          prior to calling this function.  If the assigned index already contains the
          sparse data passed in, it will be overwritten.

          After calling this, the data at the specified index will be associated with
          the provided sparse data as well as any data it was previously associated with.

          @tparam Fields The sparse fields to be inserted.  Do not wrap with SparseField<>.
                         If any field does not exist in the point cloud, an exception
                         will be thrown.
          @param index The index to insert sparse data at.  If this index does not exist
                       in the point cloud, an exception will be thrown.
          @param data The sparse data to be inserted.  If the data already exists, it will be
                      overwritten */
      template <class ... Fields>
      void insertSparse( size_t const index, StreamableGenericBag<Fields...> const & data );

      //! Appends all data from another point cloud to this one
      /*! This will add all of the data from another point cloud to the end of the data
          in this point cloud, increasing its size by the size of the other point cloud.

          This is intended to combine two same configured point clouds together and is not
          meant for use with mixed types, since the behavior in that situation can be
          ambiguous.

          If the two point clouds do not have identical configurations, an exception will
          be thrown.

          Dense data will merely be appended to the current data.  Sparse data in the other
          point cloud will have its index adjusted by the new starting index of data from
          the other point cloud.  For example, if our current cloud is size 100 and we merge
          a size 50 cloud, a sparse field from the other cloud that was at index 2 is now at
          index 102.

          @return A reference to this, which will now contain the data from the other cloud as well
          @throws PointCloud2FieldsException If the two clouds do not have exactly the same set
                                             of fields */
      PointCloud2 & append( PointCloud2 const other );

      //! Remove all data (from every field) associated with a specific index
      void remove( size_t index );

      //! Remove the sparse data of a specific field associated with a point
      /*! It is not necessary to wrap the template parameter with SparseField<>.
          If specified, it will be stripped automatically.

          @throws PointCloud2FieldsException If the requested field does not exist in the cloud */
      template <class Field>
      void remove( size_t index );

      //! Remove all data (from every field) associated with a specific index,
      //! not preserving ordering
      /*! This is generally a faster operation than remove() but will not
          preserve the ordering of points within the cloud */
      void quickRemove( size_t index );

      //! Remove all data (from every field) associated with every index in a subset
      //! not preserving ordering
      /*! This is generally a faster operation than calling remove() or quickRemove() on several
          indices to remove.

          Because quickRemove does not preserve ordering, the input must be sorted or the sort
          flag should be specified so that this function handles the sorting.

          @param indices The subset to remove
          @param sort Whether we need to sort the input */
      void quickRemove( Indices const indices, bool sort = false );

      //! @}

      /*! @name Memory manipulation and reference counting
          Functionality for comparing and manipulating the actual reference
          counted memory of the point cloud */
      //! @{

      //! Performs a deep copy of the underlying data
      /*! After calling deepcopy, a deep copy of all underlying data will occur and this PointCloud2
          will have unique ownership of its data until another reference is created.

          The reference count will be one after this operation and any existing references will be
          decremented. */
      void deepCopy();

      //! Check whether this cloud is equal (same internal data) as some other
      bool operator==( PointCloud2 const & other ) const;

      //! Check whether this cloud is not equal (not same internal data) as some other
      bool operator!=( PointCloud2 const & other ) const;

      //! @}
    private:
      //! Used for iterators
      template <class ... Fields> friend struct subsetHelper;

      //! A struct that helps insert fields
      template <class ... Fields> struct addFieldHelper;
      template <class ... Fields> friend struct addFieldHelper;

      //! A struct that helps remove fields
      template <class ... Fields> struct removeFieldHelper;
      template <class ... Fields> friend struct removeFieldHelper;

      //! A struct that helps insert new data
      template <size_t Index> struct insertDataHelper;
      template <size_t Index> friend struct insertDataHelper;

      //! A struct that checks for all dense fields and that sparse fields exist, during insertion
      template <class ... T> struct insertionChecker;
      template <class ... T> friend struct insertionChecker;

      //! A struct that helps lookup existing data
      template <class RetT, class ... T> struct lookupHelper;
      template <class RetT, class ... T> friend struct lookupHelper;

      //! A struct used to build a bag of dense pointers
      template <class RetT, class ... T> struct pointerHelper;
      template <class RetT, class ... T> friend struct pointerHelper;

      //! used for checking if a list of fields constains a sparse field
      template <class ... T> struct sparseExistHelper;
      template <class ... T> friend struct sparseExistHelper;


      //! used to find the strictest subset of indices for some sparse fields
      template <class ... T> struct subsetHelper;
      template <class ... T> friend struct subsetHelper;

      //! checks that all of the fields provided are sparse
      template <class ... T> struct sparseOnlyExistHelper;
      template <class ... T> friend struct sparseOnlyExistHelper;

      //! handles inserting junk data when adding sparse data to an index
      template <class ... T> struct sparseInsertHelper;
      template <class ... T> friend struct sparseInsertHelper;

      //! Adds a dense field to the point cloud
      template <class T>
      typename std::enable_if<!std::is_base_of<SparseFieldCore, T>::value, void>::type
      addDataField();

      //! Adds a sparse field to the point cloud
      template <class T>
      typename std::enable_if<std::is_base_of<SparseFieldCore, T>::value, void>::type
      addDataField();

      //! Removes a field from the point cloud
      template <class T>
      void removeDataField();

      //! inserts data into a specific field
      /*! @param index The index to use, if a sparse entry
          @param data The data to insert */
      template <class T>
      void insertFieldData( size_t index, T const & data );

      //! gets data from a specific field
      /*! @param index The index to use */
      template <class T>
      T & getFieldData( size_t index );

      //! gets data from a specific field
      /*! @param index The index to use */
      template <class T>
      T const & getFieldData( size_t index ) const;

      //! Causes a deep copy to occur if we do not have unique access to our data
      void deepCopyIfNotUnique();

      //! insert junk (zero valued) data into all dense fields that
      //! were not specified explicitly during an insert
      /*! @param size The current number of dense fields fully specified */
      void insertEqualize( size_t const size );

      //! Invalidates all local caching
      /*! Various lookups are cached, mainly when calculating iterators, that
          must be invalidated if the structure of the underlying data changes.
          These changes can occur on the following conditions:
            Fields are added or removed to the cloud
            Data is inserted or removed from the cloud
            The memory pointer is changed */
      void invalidateCache();

    private:
      //! Copy on write memory class forward decl
      class Memory;

      //! The data associated with this cloud
      std::shared_ptr<Memory> itsData;

      //! Fast access to the size of the cloud
      size_t itsSize;

      //! Caches lookup for whether a sparse field exists in a set of fields
      mutable LookupCache itsSparseExistCache;

      //! Caches lookup for building a dense set of pointers
      mutable LookupCache itsPointerCache;

      friend class cereal::access;

      //! Handles serialization saving
      template <class Archive> inline
      void save( Archive & ar ) const
      {
        ar( itsData,
            itsSize,
            itsSparseExistCache,
            itsPointerCache );
      }

      //! Handles serialization loading
      template <class Archive> inline
      void load( Archive & ar )
      {
        ar( itsData,
            itsSize,
            itsSparseExistCache,
            itsPointerCache );

        invalidateCache();
      }
  }; // class PointCloud2

  namespace exception
  {
    //! An exception that is thrown whenever there is an error related to the requested fields
    class PointCloud2FieldsException : public nrt::exception::Exception
    {
      public:
        //! Construct a new exception for an incompatible set of fields
        PointCloud2FieldsException() noexcept;

        //! Construct a new exception when number of fields is incorrect
        PointCloud2FieldsException( size_t count, size_t expected ) noexcept;

        //! Construct a new exception with a specific field
        /*! @param field The first field that encountered an error */
        PointCloud2FieldsException( std::string const & field ) noexcept;

        //! Construct a new exception with a specific field and specific error message
        /*! @param field The first field that encountered an error
            @param message A message to be output after the field is listed */
        PointCloud2FieldsException( std::string const & field, std::string const & message ) noexcept;

        virtual ~PointCloud2FieldsException() noexcept;

        //! Get the field name that caused the error
        std::string const & field() const;

      private:
        std::string itsField;
        std::string whatstring;
    };

    //! Exception thrown when errors occur with subsets
    class PointCloud2SubsetException : public nrt::exception::Exception
    {
      public:
        //! Constructor for an empty subset
        PointCloud2SubsetException() noexcept;

        virtual ~PointCloud2SubsetException() noexcept;

      private:
        std::string whatstring;
    };
  } // namespace exception
} // namespace nrt

#include <nrt/PointCloud2/details/PointCloud2Impl.H>

#endif // INCLUDE_NRT_POINTCLOUD2_POINTCLOUD2_H
#endif // NRT_HAVE_CLOUD