networkEdge.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2006 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: netwrkEdge.h,v $ $Revision: 1.26 $ $State: Exp $
*******************************************************************************/
#ifndef networkEdge_H_
#define networkEdge_H_

#include "gdb/gdbDefines.h"
#include "gdb/networkSegment.h"
#include "gdb/networkSpecificationElement.h"
#include <assert.h>
#include <vlutil/vlConfig.h>
#include <geometry/extent.h>
#include <vector>
#include <list>
#include <memory>

class DtNetworkNode;
class DtNetworkSegmentIterator;
class DtNetworkEdgeTraverser;

//
// DtNetworkEdge represents a section of a network built using a series
// of points that does not intersect any other part of the network.
class DT_DLL_gdb DtNetworkEdge : public DtNetworkSpecificationElement 
{
public:

   typedef std::vector<DtPoint> DtPointContainer;
   typedef DtPointContainer::iterator DtPointIter;
   typedef DtPointContainer::const_iterator DtPointConstIter;
   typedef DtPointContainer::reverse_iterator DtPointReverseIter;
   typedef DtPointContainer::const_reverse_iterator DtPointConstReverseIter;

   typedef std::list<DtNetworkSegment*> DtSegmentContainer;
   typedef DtSegmentContainer::iterator DtSegmentIter;
   typedef DtSegmentContainer::const_iterator DtSegmentConstIter;
   typedef DtSegmentContainer::reverse_iterator DtSegmentReverseIter;
   typedef DtSegmentContainer::const_reverse_iterator DtSegmentConstReverseIter;

   enum DtTraversalDirection
   {
      DtForward,
      DtBackward
   };

   enum DtDirectionality
   {
      UNI_DIRECTIONAL,
      BI_DIRECTIONAL // default
   };

   // default constructor
   DtNetworkEdge();

   // destructor
   // \note Upon destruction, all connected nodes are notified 
   // that they are no longer connected to the edge.
   virtual ~DtNetworkEdge();

private:
   // copy constructor - not implemented
   DtNetworkEdge(const DtNetworkEdge& orig);

   // assignment operator - not implemented
   DtNetworkEdge& operator=(const DtNetworkEdge& orig);

public:
   // \return the DtString "DtNetworkEdge"
   virtual DtString type();

   // \return the number of points in the edge.
   unsigned int numPoints() const;

   // \return the directionality of the road.  If the road is bidirectional,
   // and the user respects this, then only forward iterators over the segments
   // may be created.  If the edge is bi-directional or if the user ignores
   // directionality, then both forward and backward iterators may be created.
   // \note The forward direction is defined as the direction from the starting
   // point of the edge to the endpoint.
   // \note Forward and Backward can also be thought of as Right and Left as they would
   // appear to an observer 
   void setDirectionality(DtDirectionality directionality);
   DtDirectionality directionality() const;


   // Return auto pointers to edge traversers for this edge.
   // \param respectDirectionality If this is true, the traverser will *not* be created for
   // one way streets if the desired direction is backwards.  
   // \note Forward can be described as the direction from the starting 
   // point of the edge to the end point.
   // \note If no parameters are supplied, a Forward traverser is returned (should never fail).
   std::auto_ptr<DtNetworkEdgeTraverser> createEdgeTraverser();
   std::auto_ptr<DtNetworkEdgeTraverser> createEdgeTraverser(DtTraversalDirection traversalDirection,
                                                             bool respectDirectionality);

   std::auto_ptr<const DtNetworkEdgeTraverser> createEdgeTraverser() const;
   std::auto_ptr<const DtNetworkEdgeTraverser> createEdgeTraverser(DtTraversalDirection traversalDirection,
                                                                   bool respectDirectionality) const;

   // \return the length of the edge, as a sum of the lengths of the
   // segments comprising the edge.
   virtual double length() const;
   // Computes the closest point on the edge to another point
   // \param pointOut the computed closest point
   // \param distance the computed distance 
   virtual void closestPoint(const DtPoint& pointIn, 
                             DtPoint& pointOut, 
                             double& distance) const;

   // Computes the distance from the edge to a point.
   // \return the closest distance to the specified point.
   virtual double distanceToPoint(const DtPoint& point) const;


   // Calculates the intersection of the projections onto the x-y plane 
   // of this edge and the specified segment. 
   // 
   // \param seg the segment to test for intersections
   // \return a boolean signifying whether or not any intersection occurred.
   virtual bool xyIntersects(const DtNetworkSegment& seg) const;


   // The same as the above function, but also calculates the specified 
   // values. 
   // \param seg the segment to test for intersections.
   // \param thisSeg a reference to the segment on this edge, if any, that
   //                intersects the specified segment.
   // \param distanceSquared the distance between the segment and the edge squared. 
   // \param thisX 
   // \param thisY These hold the closest points on this edge
   // \param otherX 
   // \param otherY These hold the closest points on the network segment
   virtual bool xyIntersects(const DtNetworkSegment& seg,
                             const DtNetworkSegment*& thisSeg,
                             double& distanceSquared,
                             double& thisX, 
                             double& thisY,
                             double& otherX, 
                             double& otherY) const;

   // Calculates the intersection of the projections onto the x-y plane 
   // of this edge and the specified edge. 
   // 
   // \param edge the edge to test for intersections
   // \param thisSeg a reference to the segment on this edge that intersects the 
   //                specified edge, if any.
   // \param otherSeg a reference to the segment on the specified edge that
   //                 intersects this edge, if any.
   // \return a boolean signifying whether or not any intersection occurred.
   virtual bool xyIntersects(const DtNetworkEdge& edge,
                             const DtNetworkSegment*& thisSeg,
                             const DtNetworkSegment*& otherSeg) const;

   // The same as the above function, but also calculates the specified 
   // values. 
   // \param edge the edge to test for intersections
   // \param thisSeg a reference to the segment on this edge that intersects the 
   //                specified edge, if any.
   // \param otherSeg a reference to the segment on the specified edge that
   //                 intersects this edge, if any.
   // \param distanceSquared the distance between the edge and the edge squared. 
   // \param thisX 
   // \param thisY these hold the closest points on this edge
   // \param otherX 
   // \param otherY these hold the closest points on the edge
   virtual bool xyIntersects(const DtNetworkEdge& edge,
                             const DtNetworkSegment*& thisSeg,
                             const DtNetworkSegment*& otherSeg,
                             double& distanceSquared,
                             double& thisX, 
                             double& thisY,
                             double& otherX, 
                             double& otherY) const;

   // get/set start and end nodes
   // \note must be the same location as the
   // start and end points of the edge.
   // 
   // \see startPoint()
   // \see endPoint()
   virtual DtNetworkNode* startNode() const;
   // \note If there is an existing start node, it is
   // notified of being replaced by another node.
   virtual void setStartNode(DtNetworkNode* node);
   virtual DtNetworkNode* endNode() const;
   // \note If there is an existing end node, it is
   // notified of being replaced by another node.
   virtual void setEndNode(DtNetworkNode* node);

   // If the specified node is either start, end, or both,
   // the associated member is set to 0 to remove the 
   // connection to the node.
   // \note Used by nodes to remove themselves from edges
   // when they are deleted.  Edges may need to respond by
   // creating/setting another node if appropriate.
   virtual void removeConnection(DtNetworkNode* node);

   // \return the first and last endpoints respectively
   virtual DtPoint endpoint0() const;
   virtual DtPoint endpoint1() const;

   virtual bool pointInEdge(const DtPoint& point) const;
   virtual bool addPoint(const DtPoint& newPoint);
   virtual bool addPointToStart(const DtPoint& newPoint);

   // Returns the point at the particular index
   const DtPoint& point(int i) const;
   DtPoint& point(int i);

   // \return the extent of the edge
   virtual DtExtent extent() const;

   // \return an actual iterator, const or non-const, to the beginning or 
   // the end of the list of segments
   // \note These give *direct* access to the edges segments, regardless of 
   // directionality!
   DtPointIter pointsBegin();
   DtPointConstIter pointsBegin() const;

   DtPointIter pointsEnd();
   DtPointConstIter pointsEnd() const;

   // \return a reverse iterator, const or non-const, to the beginning or 
   // the end of the segments
   // \note These give *direct* access to the edges segments, regardless of 
   // directionality!
   DtPointReverseIter rPointsBegin();
   DtPointConstReverseIter rPointsBegin() const;

   DtPointReverseIter rPointsEnd();
   DtPointConstReverseIter rPointsEnd() const;


   // Returns a new segment in the edge.  
   // \note If this edge is associated with a vector network,
   // the segment is owned by the vector network.  Otherwise,
   // it is owned by the edge.
   DtNetworkSegment* newSegment();
   
   // \return an actual iterator, const or non-const, to the beginning or 
   // the end of the list of segments
   // \note These give *direct* access to the edges segments, regardless of 
   // directionality!
   DtSegmentIter segmentsBegin();
   DtSegmentConstIter segmentsBegin() const;

   DtSegmentIter segmentsEnd();
   DtSegmentConstIter segmentsEnd() const;

   // \return a reverse iterator, const or non-const, to the beginning or 
   // the end of the segments
   // \note These give *direct* access to the edges segments, regardless of 
   // directionality!
   DtSegmentReverseIter rSegmentsBegin();
   DtSegmentConstReverseIter rSegmentsBegin() const;

   DtSegmentReverseIter rSegmentsEnd();
   DtSegmentConstReverseIter rSegmentsEnd() const;

   virtual void setVectorNetwork(DtVectorNetwork* vectorNetwork);
   virtual DtVectorNetwork* vectorNetwork() const;

   // Returns references to the lists of points and segments contained
   // in the edge
   // \note Users should almost never need to use these functions, and should 
   // be very careful when doing so as these functions may lead to corruption
   // of the edge instance.
   DtPointContainer& points();
   const DtPointContainer& points() const;
   DtSegmentContainer& segments();
   const DtSegmentContainer& segments() const;

   virtual int sizeInBytes() const;

protected:
   bool testInvariant() const;

   DtVectorNetwork*     myVectorNetwork;
   DtDirectionality     myDirectionality;
   DtPointContainer     myPoints;
   // edge owns these segments and is responsible for deleting them.
   DtSegmentContainer   mySegments;

   // Does not own the nodes, and should never delete them
   DtNetworkNode*       myStartNode;
   DtNetworkNode*       myEndNode;

   double               myLength;
};

// For backwards compatibility - remove later.
typedef DtNetworkEdge::DtSegmentIter DtNetworkSegmentIter;
typedef DtNetworkEdge::DtSegmentConstIter DtNetworkSegmentConstIter;
typedef DtNetworkEdge::DtSegmentReverseIter DtNetworkSegmentReverseIter;
typedef DtNetworkEdge::DtSegmentConstReverseIter DtNetworkSegmentConstReverseIter;

inline const DtPoint& DtNetworkEdge::point(int i) const
{
   return myPoints[i];
}

inline DtPoint& DtNetworkEdge::point(int i)
{
   return myPoints[i];
}

#endif