Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/outofcore/include/pcl/outofcore/outofcore_base_data.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2012, Willow Garage, Inc.
00006  *
00007  *  All rights reserved.
00008  *
00009  *  Redistribution and use in source and binary forms, with or without
00010  *  modification, are permitted provided that the following conditions
00011  *  are met:
00012  *
00013  *   * Redistributions of source code must retain the above copyright
00014  *     notice, this list of conditions and the following disclaimer.
00015  *   * Redistributions in binary form must reproduce the above
00016  *     copyright notice, this list of conditions and the following
00017  *     disclaimer in the documentation and/or other materials provided
00018  *     with the distribution.
00019  *   * Neither the name of Willow Garage, Inc. nor the names of its
00020  *     contributors may be used to endorse or promote products derived
00021  *     from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00027  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034  *  POSSIBILITY OF SUCH DAMAGE.
00035  *
00036  *  $Id$
00037  */
00038 
00039 #ifndef PCL_OUTOFCORE_OCTREE_BASE_METADATA_H_
00040 #define PCL_OUTOFCORE_OCTREE_BASE_METADATA_H_
00041 
00042 #include <pcl/pcl_macros.h>
00043 #include <pcl/outofcore/boost.h>
00044 #include <pcl/outofcore/cJSON.h>
00045 
00046 #include <pcl/common/eigen.h>
00047 
00048 #include <pcl/outofcore/metadata.h>
00049 
00050 //standard library
00051 #include <string>
00052 
00053 namespace pcl
00054 {
00055   namespace outofcore
00056   {
00057     /** \class OutofcoreOctreeBaseMetadata 
00058      *
00059      *  \brief Encapsulated class to read JSON metadata into memory,
00060      *  and write the JSON metadata associated with the octree root
00061      *  node. This is global information that is not the same as the
00062      *  metadata for the root node. Inherits OutofcoreAbstractMetadata
00063      *  interface for metadata in \b pcl_outofcore.
00064 
00065      *
00066      *  This class encapsulates the outofcore base metadata
00067      *  serialization/deserialization. At the time it was written,
00068      *  this depended on cJSON to write JSON objects to disk. This
00069      *  class can be extended to have arbitrary JSON ascii metadata
00070      *  fields saved to the metadata object file on disk. The class
00071      *  has been encapuslated to abstract the detailso of the on-disk
00072      *  format from the outofcore implementation. For example, the
00073      *  format could be changed to XML/YAML, or any dynamic format at
00074      *  some point.
00075      *
00076      *  The JSON file is formatted in the following way:
00077      *  \verbatim
00078      {
00079        "name": "nameoftree",
00080        "version": 3,
00081        "pointtype": "urp",               #(needs to be changed*)
00082        "lod": 3,                         #(depth of the tree
00083        "numpts":  [X0, X1, X2, ..., XD], #total number of points at each LOD
00084        "coord_system": "ECEF"            #the tree is not affected by this value
00085      }
00086      \endverbatim
00087      *
00088      *  Any properties not stored in the metadata file are computed
00089      *  when the file is loaded. By convention, and for historical
00090      *  reasons from the original Urban Robotics implementation, the
00091      *  JSON file representing the overall tree is a JSON file named
00092      *  with the ".octree" extension.
00093      *
00094      *  \ingroup outofcore
00095      *  \author Stephen Fox (foxstephend@gmail.com)
00096      */
00097     class PCL_EXPORTS OutofcoreOctreeBaseMetadata : public OutofcoreAbstractMetadata
00098     {
00099       public:
00100         /** \brief Empty constructor */
00101         OutofcoreOctreeBaseMetadata ();
00102         /** \brief Load metadata from disk 
00103          *
00104          *  \param[in] path_arg Location of JSON metadata file to load from disk
00105          */
00106         OutofcoreOctreeBaseMetadata (const boost::filesystem::path& path_arg);
00107         /** \brief Default destructor*/
00108         ~OutofcoreOctreeBaseMetadata ();
00109 
00110         /** \brief Copy constructor */
00111         OutofcoreOctreeBaseMetadata (const OutofcoreOctreeBaseMetadata& orig);
00112 
00113         /** \brief et the outofcore version read from the "version" field of the JSON object */
00114         int 
00115         getOutofcoreVersion () const;
00116         /** \brief Set the outofcore version stored in the "version" field of the JSON object */
00117         void 
00118         setOutofcoreVersion (const int version);
00119 
00120         /** \brief Gets the name of the JSON file */
00121         boost::filesystem::path 
00122         getMetadataFilename () const;
00123         /** \brief Sets the name of the JSON file */
00124         void 
00125         setMetadataFilename (const boost::filesystem::path& path_to_metadata);
00126                 
00127         /** \brief Writes the data to a JSON file located at \ref metadata_filename_ */
00128         virtual void 
00129         serializeMetadataToDisk ();
00130 
00131         /** \brief Loads the data from a JSON file located at \ref metadata_filename_ */
00132         virtual int
00133         loadMetadataFromDisk ();
00134         /** \brief Loads the data from a JSON file located at \ref metadata_filename_ */
00135         
00136         virtual int
00137         loadMetadataFromDisk (const boost::filesystem::path& path_to_metadata);
00138 
00139         /** \brief Returns the name of the tree; this is not the same as the filename */
00140         virtual std::string
00141         getOctreeName ();
00142         /** \brief Sets the name of the tree */
00143         virtual void
00144         setOctreeName (const std::string& name_arg);
00145 
00146         virtual std::string
00147         getPointType ();
00148         /** \brief Sets a single string identifying the point type of this tree */
00149         virtual void
00150         setPointType (const std::string& point_type_arg);
00151 
00152         virtual std::vector<boost::uint64_t>&
00153         getLODPoints ();
00154         virtual std::vector<boost::uint64_t>
00155         getLODPoints () const;
00156         /** \brief Get the number of points at the given depth */
00157         virtual boost::uint64_t
00158         getLODPoints (const boost::uint64_t& depth_index) const;
00159         
00160         /** \brief Initialize the LOD vector with points all 0 */
00161         virtual void
00162         setLODPoints (const boost::uint64_t& depth);
00163         /** \brief Copy a vector of LOD points into this metadata (dangerous!)*/
00164         virtual void
00165         setLODPoints (std::vector<boost::uint64_t>& lod_points_arg);
00166 
00167         /** \brief Set the number of points at lod_index_arg manually 
00168          *  \param[in] lod_index_arg the depth at which this increments the number of LOD points
00169          *  \param[in] num_points_arg The number of points to store at that LOD
00170          *  \param[in] increment If true, increments the number of points at the LOD rather than overwriting the number of points
00171          */
00172         virtual void
00173         setLODPoints (const boost::uint64_t& lod_index_arg, const boost::uint64_t& num_points_arg, const bool increment=true);
00174         
00175         /** \brief Set information about the coordinate system */
00176         virtual void
00177         setCoordinateSystem (const std::string& coordinate_system);
00178         /** \brief Get metadata information about the coordinate system */
00179         virtual std::string
00180         getCoordinateSystem () const;
00181 
00182         /** \brief Set the depth of the tree corresponding to JSON "lod:number". This should always be equal to LOD_num_points_.size()-1 */
00183         virtual void
00184         setDepth (const boost::uint64_t& depth_arg);
00185         virtual boost::uint64_t
00186         getDepth () const;
00187 
00188         /** \brief Provide operator overload to stream ascii file data*/
00189         friend std::ostream& 
00190         operator<<(std::ostream& os, const OutofcoreOctreeBaseMetadata& metadata_arg);
00191 
00192       protected:
00193         /** \brief Metadata (JSON) file pathname (octree extension JSON file) */
00194         boost::filesystem::path metadata_filename_;
00195 
00196         /** \brief Outofcore library version identifier; maps to JSON "version":int */
00197         int outofcore_version_;
00198 
00199         /** \brief Coordinate system; maps to JSON "coord_sys":string */
00200         std::string coordinate_system_;
00201 
00202         /** \brief Name of the tree (which could be used, for example, as the name of a layer); maps to JSON "name":string*/
00203         std::string tree_name_;
00204 
00205         /** \brief Delineates the point types of the field; maps to JSON "pointtype":string:
00206          *  \note This is inconsistent with "point type" fields used in PCLPointCloud2 and in other places in PCL
00207          */
00208         std::string point_type_;
00209         
00210         /** \brief Depth of the tree (which is the number of levels of depth); maps to JSON "lod":int*/
00211         boost::uint64_t levels_of_depth_;
00212         
00213         /** \brief Vector of number of points at each LOD. For a tree with no LOD, all fields will be zero except for the field indexed by LOD_points_[levels_of_depth]; maps to JSON "numpts":int array*/
00214         std::vector<boost::uint64_t> LOD_num_points_;
00215 
00216         /** \brief Writes the JSON metadata to a string */
00217         virtual void
00218         writeMetadataString (std::vector<char>& buf);
00219     };
00220   }//namespace outofcore
00221 }//namespace pcl
00222   
00223 #endif // PCL_OUTOFCORE_OCTREE_BASE_METADATA_H_