index.hpp

Go to the documentation of this file.

/******************************************************************************
 * $Id$
 *
 * Project:  libLAS - http://liblas.org - A BSD library for LAS format data.
 * Purpose:  LAS index class 
 * Author:   Gary Huber, gary@garyhuberart.com
 *
 ******************************************************************************
 * Copyright (c) 2010, Gary Huber, gary@garyhuberart.com
 *
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following 
 * conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright 
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright 
 *       notice, this list of conditions and the following disclaimer in 
 *       the documentation and/or other materials provided 
 *       with the distribution.
 *     * Neither the name of the Martin Isenburg or Iowa Department 
 *       of Natural Resources nor the names of its contributors may be 
 *       used to endorse or promote products derived from this software 
 *       without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
 * OF SUCH DAMAGE.
 ****************************************************************************/

#ifndef LIBLAS_LASINDEX_HPP_INCLUDED
#define LIBLAS_LASINDEX_HPP_INCLUDED

#include <liblas/reader.hpp>
#include <liblas/header.hpp>
#include <liblas/bounds.hpp>
#include <liblas/variablerecord.hpp>
#include <liblas/detail/index/indexcell.hpp>
#include <liblas/export.hpp>

// std
#include <stdexcept> // std::out_of_range
#include <cstdio>   // file io
#include <iostream> // file io
#include <cstdlib> // std::size_t
#include <vector> // std::vector

namespace liblas {

#define LIBLAS_INDEX_MAXMEMDEFAULT  10000000    // 10 megs default
#define LIBLAS_INDEX_MINMEMDEFAULT  1000000 // 1 meg at least has to be allowed
#define LIBLAS_INDEX_VERSIONMAJOR   1
#define LIBLAS_INDEX_VERSIONMINOR   2   // minor version 2 begins 11/15/10
#define LIBLAS_INDEX_MAXSTRLEN  512
#define LIBLAS_INDEX_MAXCELLS   250000
#define LIBLAS_INDEX_OPTPTSPERCELL  100
#define LIBLAS_INDEX_MAXPTSPERCELL  1000
#define LIBLAS_INDEX_RESERVEFILTERDEFAULT   1000000 // 1 million points will be reserved on large files for filter result

// define this in order to fix problem with last bytes of last VLR getting corrupted
// when saved and reloaded from index or las file.
#define LIBLAS_INDEX_PADLASTVLR

typedef std::vector<uint8_t> IndexVLRData;
typedef std::vector<liblas::detail::IndexCell> IndexCellRow;
typedef std::vector<IndexCellRow>   IndexCellDataBlock;

class LAS_DLL IndexData;
class LAS_DLL IndexIterator;

// Index class is the fundamental object for building and filtering a spatial index of points in an LAS file.
// An Index class doesn't do anything until it is configured with an IndexData object (see below).
//      You instantiate an Index object first and then pass it an IndexData or you can construct the Index with an 
//      IndexData. Nothing happens until the Index is told what to do via the configuration with IndexData.
//      For details on configuration options see IndexData below.

// Once an index exists and is configured, it can be used to filter the point set in the LAS file for which it
//      was built. The points have to be what they were when the index was built. The index is not automatically 
//      updated if the point set is changed. The index becomes invalid if either the number of points is changed,
//      the order of points is changed or the location of any points is changed. The Validate function is run to
//      determine as best it can the validity of the stored index but it isn't perfect. It can only determine if
//      the number of points has changed or the spatial extents of the file have changed.

// The user can constrain the memory used in building an index if that is believed to be an issue. 
//      The results will be the same but some efficiency may be lost in the index building process.

//  Data stored in index header can be examined for determining suitability of index for desired purpose.
//      1) presence of z-dimensional cell structure is indicated by GetCellsZ() called on the Index.
//      2) Index author GetIndexAuthorStr() - provided by author at time of creation
//      3) Index comment GetIndexCommentStr() - provided by author at time of creation
//      4) Index creation date GetIndexDateStr() - provided by author at time of creation
//  The latter fields are not validated in any way by the index building code and are just three fields 
//      which can be used as the user sees fit. Maximum length is LIBLAS_INDEX_MAXSTRLEN - 1.

// Obtaining a filtered set of points requires that a valid index exist (see above).
// The IndexData class is used again to pass the extents of the filter to the Index. By making any high/low
//      bounds coordinate pair equal, that dimension is ignored for the purposes of filtering. Note that Z dimension 
//      discrimination is still available even if z-binning was not invoked during index creation. Filtering with
//      the z dimension may be slower in that event but no less successful.

// A filter operation is invoked with the command:
//      const std::vector<uint32_t>& Filter(IndexData const& ParamSrc);
// The return value is a vector of point ID's. The points can be accessed from the LAS file in the standard way
//      as the index in no way modifies them or their sequential order.
// Currently only one, two or three dimensional spatial window filters are supported. See IndexData below for 
//      more info on filtering.

class LAS_DLL Index
{
public:
    Index();
    Index(IndexData const& ParamSrc);
    ~Index();
    
    // Blocked copying operations, declared but not defined.
    Index(Index const& other);
    Index& operator=(Index const& rhs);
    
private:

    Reader *m_reader;
    Reader *m_idxreader;
    Header m_pointheader;
    Header m_idxheader;
    Bounds<double> m_bounds;
    bool m_indexBuilt, m_tempFileStarted, m_readerCreated, m_readOnly, m_writestandaloneindex, m_forceNewIndex;
    int m_debugOutputLevel;
    uint8_t m_versionMajor, m_versionMinor;
    uint32_t m_pointRecordsCount, m_maxMemoryUsage, m_cellsX, m_cellsY, m_cellsZ, m_totalCells, 
        m_DataVLR_ID;
    liblas::detail::TempFileOffsetType m_tempFileWrittenBytes;
    double m_rangeX, m_rangeY, m_rangeZ, m_cellSizeZ, m_cellSizeX, m_cellSizeY;
    std::string m_tempFileName; 
    std::string m_indexAuthor;
    std::string m_indexComment;
    std::string m_indexDate;
    std::vector<uint32_t> m_filterResult;
    std::ostream *m_ofs;
    FILE *m_tempFile, *m_outputFile;
    FILE *m_debugger;
    
    void SetValues(void);
    bool IndexInit(void);
    void ClearOldIndex(void);
    bool BuildIndex(void);
    bool Validate(void);
    uint32_t GetDefaultReserve(void);
    bool LoadIndexVLR(VariableRecord const& vlr);
    void SetCellFilterBounds(IndexData & ParamSrc);
    bool FilterOneVLR(VariableRecord const& vlr, uint32_t& i, IndexData & ParamSrc, bool & VLRDone);
    bool FilterPointSeries(uint32_t & PointID, uint32_t & PointsScanned, 
        uint32_t const PointsToIgnore, uint32_t const x, uint32_t const y, uint32_t const z, 
        liblas::detail::ConsecPtAccumulator const ConsecutivePts, IndexIterator *Iterator, 
        IndexData const& ParamSrc);
    bool VLRInteresting(int32_t MinCellX, int32_t MinCellY, int32_t MaxCellX, int32_t MaxCellY, 
        IndexData const& ParamSrc);
    bool CellInteresting(int32_t x, int32_t y, IndexData const& ParamSrc);
    bool SubCellInteresting(int32_t SubCellID, int32_t XCellID, int32_t YCellID, IndexData const& ParamSrc);
    bool ZCellInteresting(int32_t ZCellID, IndexData const& ParamSrc);
    bool FilterOnePoint(int32_t x, int32_t y, int32_t z, int32_t PointID, int32_t LastPointID, bool &LastPtRead,
        IndexData const& ParamSrc);
    // Determines what X/Y cell in the basic cell matrix a point falls in
    bool IdentifyCell(Point const& CurPt, uint32_t& CurCellX, uint32_t& CurCellY) const;
    // determines what Z cell a point falls in
    bool IdentifyCellZ(Point const& CurPt, uint32_t& CurCellZ) const;
    // Determines what quadrant sub-cell a point falls in
    bool IdentifySubCell(Point const& CurPt, uint32_t x, uint32_t y, uint32_t& CurSubCell) const;
    // Offloads binned cell data while building Index when cell data in memory exceeds maximum set by user
    bool PurgePointsToTempFile(IndexCellDataBlock& CellBlock);
    // Reloads and examines one cell of data from temp file
    bool LoadCellFromTempFile(liblas::detail::IndexCell *CellBlock, 
        uint32_t CurCellX, uint32_t CurCellY);
    // temp file is used to store sorted data while building index
    FILE *OpenTempFile(void);
    // closes and removes the temp file
    void CloseTempFile(void);
    // Creates a Writer from m_ofs and re-saves entire LAS input file with new index
    // Current version does not save any data following the points
    bool SaveIndexInLASFile(void);
    // Creates a Writer from m_ofs and re-saves LAS header with new index, but not with data point records
    bool SaveIndexInStandAloneFile(void);
    // Calculate index bounds dimensions
    void CalcRangeX(void)   {m_rangeX = (m_bounds.max)(0) - (m_bounds.min)(0);}
    void CalcRangeY(void)   {m_rangeY = (m_bounds.max)(1) - (m_bounds.min)(1);}
    void CalcRangeZ(void)   {m_rangeZ = (m_bounds.max)(2) - (m_bounds.min)(2);}

    // error messages
    bool FileError(const char *Reporter);
    bool InputFileError(const char *Reporter) const;
    bool OutputFileError(const char *Reporter) const;
    bool DebugOutputError(const char *Reporter) const;
    bool PointCountError(const char *Reporter) const;
    bool PointBoundsError(const char *Reporter) const;
    bool MemoryError(const char *Reporter) const;
    bool InitError(const char *Reporter) const;
    bool InputBoundsError(const char *Reporter) const;

    // debugging
    bool OutputCellStats(IndexCellDataBlock& CellBlock)  const;
    bool OutputCellGraph(std::vector<uint32_t> CellPopulation, uint32_t MaxPointsPerCell)  const;
    
public:
    // IndexFailed and IndexReady can be used to tell if an Index is ready for a filter operation
    bool IndexFailed(void)  const {return (! m_indexBuilt);}
    bool IndexReady(void)  const {return (m_indexBuilt);}
    // Prep takes the input data and initializes Index values and then either builds or examines the Index
    bool Prep(IndexData const& ParamSrc);
    // Filter performs a point filter using the bounds in ParamSrc
    const std::vector<uint32_t>& Filter(IndexData & ParamSrc);
    IndexIterator* Filter(IndexData const& ParamSrc, uint32_t ChunkSize);
    IndexIterator* Filter(double LowFilterX, double HighFilterX, double LowFilterY, double HighFilterY, 
        double LowFilterZ, double HighFilterZ, uint32_t ChunkSize);
    IndexIterator* Filter(Bounds<double> const& BoundsSrc, uint32_t ChunkSize);
    
    // Return the bounds of the current Index
    double GetMinX(void) const  {return (m_bounds.min)(0);}
    double GetMaxX(void) const  {return (m_bounds.max)(0);}
    double GetMinY(void) const  {return (m_bounds.min)(1);}
    double GetMaxY(void) const  {return (m_bounds.max)(1);}
    double GetMinZ(void) const  {return (m_bounds.min)(2);}
    double GetMaxZ(void) const  {return (m_bounds.max)(2);}
    // Ranges are updated when an index is built or the index header VLR read
    double GetRangeX(void) const    {return m_rangeX;}
    double GetRangeY(void) const    {return m_rangeY;}
    double GetRangeZ(void) const    {return m_rangeZ;}
    Bounds<double> const& GetBounds(void) const {return m_bounds;}
    // Return the number of points used to build the Index
    uint32_t GetPointRecordsCount(void) const   {return m_pointRecordsCount;}
    // Return the number of cells in the Index
    uint32_t GetCellsX(void) const  {return m_cellsX;}
    uint32_t GetCellsY(void) const  {return m_cellsY;}
    // Return the number of Z-dimension cells in the Index. Value is 1 if no Z-cells were created during Index building
    uint32_t GetCellsZ(void) const  {return m_cellsZ;}
    // 42 is the ID for the Index header VLR and 43 is the normal ID for the Index data VLR's
    // For future expansion, multiple indexes could assign data VLR ID's of their own choosing
    uint32_t GetDataVLR_ID(void) const  {return m_DataVLR_ID;}
    // Since the user can define a Z cell size it is useful to examine that for an existing index
    double GetCellSizeZ(void) const {return m_cellSizeZ;}
    // Return values used in building or examining index
    FILE *GetDebugger(void) const   {return m_debugger;}
    bool GetReadOnly(void) const    {return m_readOnly;}
    bool GetStandaloneIndex(void) const {return m_writestandaloneindex;}
    bool GetForceNewIndex(void) const   {return m_forceNewIndex;}
    uint32_t GetMaxMemoryUsage(void) const  {return m_maxMemoryUsage;}
    int GetDebugOutputLevel(void) const {return m_debugOutputLevel;}
    // Not sure if these are more useful than dangerous
    Header *GetPointHeader(void) {return &m_pointheader;}
    Header *GetIndexHeader(void) {return &m_idxheader;}
    Reader *GetReader(void) const {return m_reader;}
    Reader *GetIndexReader(void) const {return m_idxreader;}
    const char *GetTempFileName(void) const {return m_tempFileName.c_str();}
    // Returns the strings set in the index when built
    const char *GetIndexAuthorStr(void)  const;
    const char *GetIndexCommentStr(void)  const;
    const char *GetIndexDateStr(void)  const;
    uint8_t GetVersionMajor(void) const {return m_versionMajor;}
    uint8_t GetVersionMinor(void) const {return m_versionMinor;}
    // Methods for setting values used when reading index from file to facilitate moving reading function into
    // separate IndexInput object at a future time to provide symmetry with IndexOutput
    void SetDataVLR_ID(uint32_t DataVLR_ID) {m_DataVLR_ID = DataVLR_ID;}
    void SetIndexAuthorStr(const char *ias) {m_indexAuthor = ias;}
    void SetIndexCommentStr(const char *ics)    {m_indexComment = ics;}
    void SetIndexDateStr(const char *ids)   {m_indexDate = ids;}
    void SetMinX(double minX)   {(m_bounds.min)(0, minX);}
    void SetMaxX(double maxX)   {(m_bounds.max)(0, maxX);}
    void SetMinY(double minY)   {(m_bounds.min)(1, minY);}
    void SetMaxY(double maxY)   {(m_bounds.max)(1, maxY);}
    void SetMinZ(double minZ)   {(m_bounds.min)(2, minZ);}
    void SetMaxZ(double maxZ)   {(m_bounds.max)(2, maxZ);}
    void SetPointRecordsCount(uint32_t prc) {m_pointRecordsCount = prc;}
    void SetCellsX(uint32_t cellsX) {m_cellsX = cellsX;}
    void SetCellsY(uint32_t cellsY) {m_cellsY = cellsY;}
    void SetCellsZ(uint32_t cellsZ) {m_cellsZ = cellsZ;}
    
}; 

// IndexData is used to pass attributes to and from the Index itself.
// How it is initialized determines what action is taken when an Index object is instantiated with the IndexData.
// The choices are:
// a) Build an index for an las file
//      1) std::ostream *ofs must be supplied as well as std::istream *ifs or Reader *reader and a full file path 
//          for writing a temp file, const char *tmpfilenme.
// b) Examine an index for an las file
//      1) std::istream *ifs or Reader *reader must be supplied for the LAS file containing the point data
//      2) if the index to be read is in a standalone file then Reader *idxreader must also be supplied
// Options for building are
//      a) build a new index even if an old one exists, overwriting the old one
//          1) forcenewindex must be true
//          2) std::ostream *ofs must be a valid ostream where there is storage space for the desired output
//      b) only build an index if none exists
//          1) forcenewindex must be false
//          2) std::ostream *ofs must be a valid ostream where there is storage space for the desired output
//      c) do not build a new index under any circumstances
//          1) readonly must be true
// Location of the index can be specified
//      a) build the index within the las file VLR structure
//          1) writestandaloneindex must be false
//          2) std::ostream *ofs must be a valid ostream where there is storage space for a full copy
//              of the LAS file plus the new index which is typically less than 5% of the original file size
//      b) build a stand-alone index outside the las file
//          1) writestandaloneindex must be true
//          2) std::ostream *ofs must be a valid ostream where there is storage space for the new index 
//              which is typically less than 5% of the original file size

// How the index is built is determined also by members of the IndexData class object.
// Options include:
//      a) control the maximum memory used during the build process
//          1) pass a value for maxmem in bytes greater than 0. 0 resolves to default LIBLAS_INDEX_MAXMEMDEFAULT.
//      b) debug messages generated during index creation or filtering. The higher the number, the more messages.
//          0) no debug reports
//          1) general info messages
//          2) status messages
//          3) cell statistics
//          4) progress status
//      c) where debug messages are sent
//          1) default is stderr
//      d) control the creation of z-dimensional cells and what z cell size to use
//          1) to turn on z-dimensional binning, use a value larger than 0 for zbinht
//      e) data can be stored in index header for later use in recognizing the index.
//          1) Index author indexauthor - provided by author at time of creation
//          2) Index comment indexcomment - provided by author at time of creation
//          3) Index creation date indexdate - provided by author at time of creation
//          The fields are not validated in any way by the index building code and are just three fields 
//          which can be used as the user sees fit. Maximum length is LIBLAS_INDEX_MAXSTRLEN - 1.

// Once an index is built, or if an index already exists, the IndexData can be configured
//      to define the bounds of a filter operation. Any dimension whose bounds pair are equal will
//      be disregarded for the purpose of filtering. Filtering on the Z axis can still be performed even if the 
//      index was not built with Z cell sorting. Bounds must be defined in the same units and coordinate
//      system that a liblas::Header returns with the commands GetMin{X|Y|Z} and a liblas::Point returns with 
//      Get{X|Y|Z}

class LAS_DLL IndexData
{
friend class Index;
friend class IndexIterator;

public:
    IndexData(void);
    IndexData(Index const& index);

    // use one of these methods to configure the IndexData with the values needed for specific tasks

    // one comprehensive method to set all the values used in index initialization
    bool SetInitialValues(std::istream *ifs = 0, Reader *reader = 0, std::ostream *ofs = 0, Reader *idxreader = 0, 
        const char *tmpfilenme = 0, const char *indexauthor = 0, 
        const char *indexcomment = 0, const char *indexdate = 0, double zbinht = 0.0, 
        uint32_t maxmem = LIBLAS_INDEX_MAXMEMDEFAULT, int debugoutputlevel = 0, bool readonly = 0, 
        bool writestandaloneindex = 0, bool forcenewindex = 0, FILE *debugger = 0);

    // set the values needed for building an index embedded in existing las file, overriding any existing index
    bool SetBuildEmbedValues(Reader *reader, std::ostream *ofs, const char *tmpfilenme, const char *indexauthor = 0, 
        const char *indexcomment = 0, const char *indexdate = 0, double zbinht = 0.0, 
        uint32_t maxmem = LIBLAS_INDEX_MAXMEMDEFAULT, int debugoutputlevel = 0, FILE *debugger = 0);

    // set the values needed for building an index in a standalone file, overriding any existing index
    bool SetBuildAloneValues(Reader *reader, std::ostream *ofs, const char *tmpfilenme, const char *indexauthor = 0, 
        const char *indexcomment = 0, const char *indexdate = 0, double zbinht = 0.0, 
        uint32_t maxmem = LIBLAS_INDEX_MAXMEMDEFAULT, int debugoutputlevel = 0, FILE *debugger = 0);

    // set the values needed for filtering with an existing index in an las file
    bool SetReadEmbedValues(Reader *reader, int debugoutputlevel = 0, FILE *debugger = 0);

    // set the values needed for filtering with an existing index in a standalone file
    bool SetReadAloneValues(Reader *reader, Reader *idxreader, int debugoutputlevel = 0, FILE *debugger = 0);

    // set the values needed for building an index embedded in existing las file only if no index already exists
    // otherwise, prepare the existing index for filtering
    bool SetReadOrBuildEmbedValues(Reader *reader, std::ostream *ofs, const char *tmpfilenme, const char *indexauthor = 0, 
        const char *indexcomment = 0, const char *indexdate = 0, double zbinht = 0.0, 
        uint32_t maxmem = LIBLAS_INDEX_MAXMEMDEFAULT, int debugoutputlevel = 0, FILE *debugger = 0);

    // set the values needed for building an index in a standalone file only if no index already exists in the las file
    // otherwise, prepare the existing index for filtering
    bool SetReadOrBuildAloneValues(Reader *reader, std::ostream *ofs, const char *tmpfilenme, const char *indexauthor = 0, 
        const char *indexcomment = 0, const char *indexdate = 0, double zbinht = 0.0, 
        uint32_t maxmem = LIBLAS_INDEX_MAXMEMDEFAULT, int debugoutputlevel = 0, FILE *debugger = 0);
    
    // set the bounds for use in filtering
    bool SetFilterValues(double LowFilterX, double HighFilterX, double LowFilterY, double HighFilterY, double LowFilterZ, double HighFilterZ, 
        Index const& index);
    bool SetFilterValues(Bounds<double> const& src, Index const& index);

    IndexData(IndexData const& other);
    IndexData& operator=(IndexData const& rhs);

private:
    void SetValues(void);
    bool CalcFilterEnablers(void);
    void Copy(IndexData const& other);
    
protected:
    Reader *m_reader;
    Reader *m_idxreader;
    IndexIterator *m_iterator;
    Bounds<double> m_filter;
    std::istream *m_ifs;
    std::ostream *m_ofs;
    const char *m_tempFileName;
    const char *m_indexAuthor;
    const char *m_indexComment;
    const char *m_indexDate;
    double m_cellSizeZ;
    double m_LowXBorderPartCell, m_HighXBorderPartCell, m_LowYBorderPartCell, m_HighYBorderPartCell;
    int32_t m_LowXCellCompletelyIn, m_HighXCellCompletelyIn, m_LowYCellCompletelyIn, m_HighYCellCompletelyIn,
        m_LowZCellCompletelyIn, m_HighZCellCompletelyIn;
    int32_t m_LowXBorderCell, m_HighXBorderCell, m_LowYBorderCell, m_HighYBorderCell,
        m_LowZBorderCell, m_HighZBorderCell;
    uint32_t m_maxMemoryUsage;
    int m_debugOutputLevel;
    bool m_noFilterX, m_noFilterY, m_noFilterZ, m_readOnly, m_writestandaloneindex, m_forceNewIndex, m_indexValid;
    FILE *m_debugger;

    void SetIterator(IndexIterator *setIt) {m_iterator = setIt;}
    IndexIterator *GetIterator(void) {return(m_iterator);}
    
public:
    double GetCellSizeZ(void) const {return m_cellSizeZ;}
    FILE *GetDebugger(void) const   {return m_debugger;}
    bool GetReadOnly(void) const    {return m_readOnly;}
    bool GetStandaloneIndex(void) const {return m_writestandaloneindex;}
    bool GetForceNewIndex(void) const   {return m_forceNewIndex;}
    uint32_t GetMaxMemoryUsage(void) const  {return m_maxMemoryUsage;}
    Reader *GetReader(void) const {return m_reader;}
    int GetDebugOutputLevel(void) const {return m_debugOutputLevel;}
    const char *GetTempFileName(void) const {return m_tempFileName;}
    const char *GetIndexAuthorStr(void)  const;
    const char *GetIndexCommentStr(void)  const;
    const char *GetIndexDateStr(void)  const;
    double GetMinFilterX(void) const    {return (m_filter.min)(0);}
    double GetMaxFilterX(void) const    {return (m_filter.max)(0);}
    double GetMinFilterY(void) const    {return (m_filter.min)(1);}
    double GetMaxFilterY(void) const    {return (m_filter.max)(1);}
    double GetMinFilterZ(void) const    {return (m_filter.min)(2);}
    double GetMaxFilterZ(void) const    {return (m_filter.max)(2);}
    void ClampFilterBounds(Bounds<double> const& m_bounds);
    void SetReader(Reader *reader)  {m_reader = reader;}
    void SetIStream(std::istream *ifs)  {m_ifs = ifs;}
    void SetOStream(std::ostream *ofs)  {m_ofs = ofs;}
    void SetTmpFileName(const char *tmpfilenme) {m_tempFileName = tmpfilenme;}
    void SetIndexAuthor(const char *indexauthor)    {m_indexAuthor = indexauthor;}
    void SetIndexComment(const char *indexcomment)  {m_indexComment = indexcomment;}
    void SetIndexDate(const char *indexdate)    {m_indexDate = indexdate;}
    void SetCellSizeZ(double cellsizez) {m_cellSizeZ = cellsizez;}
    void SetMaxMem(uint32_t maxmem) {m_maxMemoryUsage = maxmem;}
    void SetDebugOutputLevel(int debugoutputlevel)  {m_debugOutputLevel = debugoutputlevel;}
    void SetReadOnly(bool readonly) {m_readOnly = readonly;}
    void SetStandaloneIndex(bool writestandaloneindex)  {m_writestandaloneindex = writestandaloneindex;}
    void SetDebugger(FILE *debugger)    {m_debugger = debugger;}
};

class LAS_DLL IndexIterator
{
friend class Index;

protected:
    IndexData m_indexData;
    Index *m_index;
    uint32_t m_chunkSize, m_advance;
    uint32_t m_curVLR, m_curCellStartPos, m_curCellX, m_curCellY, m_totalPointsScanned, m_ptsScannedCurCell,
        m_ptsScannedCurVLR;
    uint32_t m_conformingPtsFound;

public:
    IndexIterator(Index *IndexSrc, double LowFilterX, double HighFilterX, double LowFilterY, double HighFilterY, 
        double LowFilterZ, double HighFilterZ, uint32_t ChunkSize);
    IndexIterator(Index *IndexSrc, IndexData const& IndexDataSrc, uint32_t ChunkSize);
    IndexIterator(Index *IndexSrc, Bounds<double> const& BoundsSrc, uint32_t ChunkSize);
    IndexIterator(IndexIterator const& other);
    IndexIterator& operator=(IndexIterator const& rhs);
private:
    void Copy(IndexIterator const& other);
    void ResetPosition(void);
    uint8_t MinMajorVersion(void)   {return(1);}
    uint8_t MinMinorVersion(void)   {return(2);}

public:
    const std::vector<uint32_t>& advance(int32_t n);
    const std::vector<uint32_t>& operator()(int32_t n);
    inline const std::vector<uint32_t>& operator++()    {return (advance(1));}
    inline const std::vector<uint32_t>& operator++(int) {return (advance(1));}
    inline const std::vector<uint32_t>& operator--()    {return (advance(-1));}
    inline const std::vector<uint32_t>& operator--(int) {return (advance(-1));}
    inline const std::vector<uint32_t>& operator+=(int32_t n)   {return (advance(n));}
    inline const std::vector<uint32_t>& operator+(int32_t n)    {return (advance(n));}
    inline const std::vector<uint32_t>& operator-=(int32_t n)   {return (advance(-n));}
    inline const std::vector<uint32_t>& operator-(int32_t n)    {return (advance(-n));}
    inline const std::vector<uint32_t>& operator[](int32_t n)   {return ((*this)(n));}
    bool ValidateIndexVersion(uint8_t VersionMajor, uint8_t VersionMinor)   {return (VersionMajor > MinMajorVersion() || (VersionMajor == MinMajorVersion() && VersionMinor >= MinMinorVersion()));}
};

template <typename T, typename Q>
inline void ReadVLRData_n(T& dest, IndexVLRData const& src, Q& pos)
{
    // error if reading past array end
    if (static_cast<size_t>(pos) + sizeof(T) > src.size())
        throw std::out_of_range("liblas::detail::ReadVLRData_n: array index out of range");
    // copy sizeof(T) bytes to destination
    memcpy(&dest, &src[pos], sizeof(T));
    // Fix little-endian
    LIBLAS_SWAP_BYTES_N(dest, sizeof(T));
    // increment the write position to end of written data
    pos = pos + static_cast<Q>(sizeof(T));
}

template <typename T, typename Q>
inline void ReadVLRDataNoInc_n(T& dest, IndexVLRData const& src, Q const& pos)
{
    // error if reading past array end
    if (static_cast<size_t>(pos) + sizeof(T) > src.size())
        throw std::out_of_range("liblas::detail::ReadVLRDataNoInc_n: array index out of range");
    // copy sizeof(T) bytes to destination
    memcpy(&dest, &src[pos], sizeof(T));
    // Fix little-endian
    LIBLAS_SWAP_BYTES_N(dest, sizeof(T));
}

template <typename T, typename Q>
inline void ReadeVLRData_str(char * dest, IndexVLRData const& src, T const srclen, Q& pos)
{
    // error if reading past array end
    if (static_cast<size_t>(pos) + static_cast<size_t>(srclen) > src.size())
        throw std::out_of_range("liblas::detail::ReadeVLRData_str: array index out of range");
    // copy srclen bytes to destination
    memcpy(dest, &src[pos], srclen);
    // increment the write position to end of written data
    pos = pos + static_cast<Q>(srclen);
}

template <typename T, typename Q>
inline void ReadVLRDataNoInc_str(char * dest, IndexVLRData const& src, T const srclen, Q pos)
{
    // error if reading past array end
    if (static_cast<size_t>(pos) + static_cast<size_t>(srclen) > src.size())
        throw std::out_of_range("liblas::detail::ReadVLRDataNoInc_str: array index out of range");
    // copy srclen bytes to destination
    std::memcpy(dest, &src[pos], srclen);
}

} // namespace liblas

#endif // LIBLAS_LASINDEX_HPP_INCLUDED