SpatialQueryDescriptor.hpp

#ifndef OPALS_SPATIAL_QUERY_DESCRIPTOR_HPP_INCLUDED
#define OPALS_SPATIAL_QUERY_DESCRIPTOR_HPP_INCLUDED

#pragma once

#include "opals/Vector.hpp"
#include "opals/String.hpp"
#include "opals/CustomOptionType.hpp"

//forward declaration
namespace DM {
  class IGeometry;
}

namespace opals
{
  /// Describes a spatial selection.
  /** OPALS supports two types of spatial queries:
      - k nearest neighbour queries (kNN) and
      - region queries based on 2D or 3D geometry objects (see RegionType::Type).
      SpatialQueryDescriptor describes one of those query types, or a combination thereof, which returns up to k objects that are inside the given region.
      kNN queries return the results ordered in ascending distance from the queried position, where distance is defined according to the kNN-Dimension (2d or 3d). 
      Region queries return objects in unspecified order.
      A certain order of results for kNN, region, and combined queries can be forced via SortOrder::Type.
           
      Syntax for constructor represented as railroad diagrams:
      
      \htmlinclude spatial_query_descriptor_diag.xht

      Syntax for constructor in EBNF:
      \code
      SpatialQuery ::=
      (   GeometryQuery ( NnQuery )?
        | NnQuery ( GeometryQuery )?
      )
      ( ( "ORDER" "=" )? ( "UNSORTED" | "ASC2D" | "ASC3D" ) )?

      RegionQuery ::=
        RegionQuery2D
      | RegionQuery3D

      RegionQuery2D ::=
        "WINDOW" "(" Length Width? ")"
      | "CIRCLE" "(" Radius ")"

      RegionQuery3D ::=
        "CYLINDER" "(" Radius ( Height | MinMax ) ")"
      | "BOX" "(" Length Width? ( Height | MinMax )? ")"
      | "SPHERE" "(" Radius ")"

      NnQuery ::=
        NnQuery2D
      | NnQuery3D

      NnQuery2D ::=
        "NN2D" "(" Count ( ( "MODE" "=" )? ( "ORDINARY" | "QUADRANT" ) )? ")"

      NnQuery3D ::=
        "NN3D" "(" Count ( ( "MODE" "=" )? ( "ORDINARY" | "OCTANT" ) )? ")"

      Count ::= ( "COUNT" "=" )? Integer
  

      Length ::= ( "LENGTH" "=" )? Real
      Width  ::= ( "WIDTH"  "=" )? Real
      Height ::= ( "HEIGHT" "=" )? Real
      Radius ::= ( "RADIUS" "=" )? Real
      MinMax ::= ( "MIN"    "=" )? Real ( "MAX"    "=" )? Real
      \endcode

      \author JO, WK
      \date   24.05.2013
  */
  class OPALS_API SpatialQueryDescriptor : public CustomOptionType<SpatialQueryDescriptor>
  {
  public:
    /// Dimensionality of nearest neighbor selection 
    struct KNNDim {
      enum Type {
        d2 = 2,
        d3 = 3,

        Count
      };
    };

    /// k-Nearest neighbor mode
    struct KNNSelection {
      enum Type {
        ordinary, ///< selects k nearest neighbors according to distance, irrespective of direction
        quadrant, ///< selects kNN equally distributed across all quadrants
        octant,   ///< selects kNN equally distributed across all octants

        Count
      };
    };

    /// Types supported by region queries
    struct RegionType {
      enum Type {
        // 2D
        window    = 4,  ///< axis-aligned rectangle defined by 4 values (xmin, ymin, xmax, ymax)
        circle    = 6,  ///< circle defined by 1 value (radius)

        // 3D
        box       = 5,  ///< axis-aligned rectangular cuboid defined by 6 values (xmin, ymin, zmin, xmax, ymax, zmax)
        sphere    = 7,  ///< sphere defined by 1 value (radius)
        cylinder  = 8,  ///< cylinder defined by 3 values (radius, zmin, zmax)

        Count
      };
      static int getDim( Type type ); ///< dimensionality of regionType: 2-D, 3-D, or undefined==0
    };

    /// Sort order of results
    struct SortOrder {
      enum Type {
        unsorted, ///< results are in unspecified order
        asc2d,    ///< results are sorted ascending by 2d distance from query position
        asc3d,    ///< results are sorted ascending by 3d distance from query position

        Count
      };
    };

    /// Construct from the given string that must adhere to the <a href="#SpatialQuery">syntax</a>, if not empty.
    SpatialQueryDescriptor( const String &definition = String() );

#ifdef __GNUC__
    typedef bool (SpatialQueryDescriptor::*unspecified_bool_type) ();
#else
    typedef bool (SpatialQueryDescriptor::*unspecified_bool_type) () const;
#endif

#ifdef __GNUC__
    operator unspecified_bool_type();
#else
    operator unspecified_bool_type() const;
#endif

#ifdef __GNUC__
    bool isEmpty(); // const removed (gcc error: forming reference to qualified function type) 
#else
    bool isEmpty() const;
#endif

    /// \name kNN query
    ///@{
#ifdef __GNUC__
    bool isKNNQuery(); // const removed (gcc error: forming reference to qualified function type)
#else
    bool isKNNQuery() const;
#endif

    unsigned           getKNNCount()     const;
    KNNDim::Type       getKNNDim()       const;
    KNNSelection::Type getKNNSelection() const;
    
    void setKNN( unsigned k, KNNDim::Type knnDim, KNNSelection::Type knnSelection = KNNSelection::ordinary );
    void resetKNN();
    ///}@


    /// \name region query
    ///@{
#ifdef __GNUC__
    bool isRegionQuery(); // const removed (gcc error: forming reference to qualified function type)
#else
    bool isRegionQuery() const;
#endif


    RegionType::Type      getRegionType()   const;
    const Vector<double>& getRegionCoords() const;

    void setRegion( RegionType::Type type, const Vector<double> &coords );
    void resetRegion();

    /// create geometry from regionType and regionCoords
    DM::IGeometry*  createRegion() const;
    /// set regionType and regionCoords from geometry
    void setRegion( const DM::IGeometry& geometry );
    ///}@


    /// \name sort order
    ///@{
    SortOrder::Type getSortOrder() const;
    void setSortOrder( SortOrder::Type type );
    ///}@

    /// \name CustomOptionType interface
    ///@{
    static const char * help();
    static const char * syntax();
    static bool exportsPythonType();
    ///}@

  private:
    unsigned           knnCount;     ///< Number of nearest neighbors to be selected (0 -> no kNN query)
    KNNDim::Type       knnDim;       ///< Dimensionality of nearest neighbor selection 
    KNNSelection::Type knnSelection; ///< Nearest neighbor selection mode

    RegionType::Type  regionType;    ///< Region query object (RegionType::none -> no region query)
    Vector<double>    regionCoords;  ///< Coordinates of the query region
    
    SortOrder::Type   sortOrder;     ///< Sort order of region query results
  };
}

#endif //OPALS_SPATIAL_QUERY_DESCRIPTOR_HPP_INCLUDED