base/Path

Go to the documentation of this file.

/****************************************************************************
  Copyright (C)2002 David Jung <opensim@pobox.com>

  This program/file 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 2 of the License, or
  (at your option) any later version.
  
  This program 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. (http://www.gnu.org)
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  
  $Id: Path 1029 2004-02-11 20:45:54Z jungd $
  $Revision: 1.6 $
  $Date: 2004-02-11 15:45:54 -0500 (Wed, 11 Feb 2004) $
  $Author: jungd $
 
****************************************************************************/

#ifndef _BASE_PATH_
#define _BASE_PATH_

#include <base/base>
#include <base/Serializable>
#include <base/Externalizable>
#include <base/Point3>
#include <base/Orient>
#include <base/Vector>
#include <base/Expression>

#include <base/PathRep>
#include <base/LineSegPathRep>
#include <base/WaypointPathRep>


namespace base {


/**
 *  A Path specifies a bounded inifinite number of continous
 *  points in 6-space (cartesian position via Point3 and
 *  orientation via Orient).  The points are expressed
 *  parametrically in terms of s:[0..1] over the path length.
 */
class Path : public Serializable, public Externalizable
{
public:
  /// default path - all points are 0
  Path();

  /// copy path p
  Path(const Path& p);

  /// simple line segment start[position|orientation] - end[position|orientation]
  Path(const Point3& sp, const Orient& so, const Point3& ep, const Orient& eo);

  /// a set of 'waypoints' - actually points and their corresponding orientations.
  /// if deltas is true, the arrays are considered to specify the inter-waypoint deltas instead
  ///  (with the first point/orient being 0)
  Path(const array<Point3>& points, const array<Orient>& orients = array<Orient>(), bool deltas=false);

  /// a set of 'waypoints'.  If vector dim is 3, specifies position only; dim 6, specifies
  ///  position and orientation using the EulerRPY (roll, pitch, yaw) convention; dim 7
  ///  specifies position and orientation as a quaternion qx,qy,qz,qw.
  /// if deltas is true, the arrays are considered to specify the inter-waypoint deltas instead
  ///  (with the first point/orient being 0)
  Path(const array<Vector>& points, bool deltas=false);

  /// arbitrary path defined by symbolic expressions for x,y,z,qx,qy,qz,qw in terms of s
  Path(const ExpressionVector& p);


  virtual String className() const { return String("Path"); }

  /// get cartesian position at s:[0..1]
  Point3 position(Real s) const { return rep->position(s); }

  /// get orientation at s:[0..1]
  Orient orientation(Real s) const { return rep->orientation(s); }

  /// discard distinguished points and replace them by 'samples' distingushed points over s=[0..1]
  void resample(Int samples=100);
  
  /// add distinguished points as necessary to ensure that distance between the positions of any pair of distinguished points is <= dxmax
  void resample(const Real dxmax);

  /// get application defined coordinate frame specifier.
  /// Some means of creating a Path provide a coordinate frame specifier. e.g. xml externalization
  ///  this returns that string (or whatever was set via setCoordFrame() - defaults to the empty String)
  const String& getCoordFrame() const { return frame; }

  /// set application defined coordinate frame specifier.
  void setCoordFrame(const String& coordFrame) { frame=coordFrame; }


  /// get application defined unit specifier.
  /// Some means of creating a Path provide unit specifier. e.g. xml externalization
  ///  this returns that string (or whatever was set via setUnits() - defaults to the empty String)
  const String& getUnits() const { return units; }
  
  /// set application defined unit specifier.
  void setUnits(const String& unitSpecifier) { units = unitSpecifier; }


  /// some values of s may correspond to distinguished points along a path.
  ///  the values s=0 and s=1 are always distinguished values. For example,
  ///  if the path was specified using waypoints, then there will be a
  ///  distinguished value of s for each waypoint.  0 <= i < numDistinguishedValues()
  Real distinguishedValue(Int i) const { return rep->distinguishedValue(i); }

  Int numDistinguishedValues() const ///< number of distinguished s values
  { return rep->numDistinguishedValues(); }

  /// translate the path position by t
  void translate(const Vector3& t) { rep->translate(t); }

  /// rotate the path orientation by r
  void rotate(const Quat4& r) { rep->rotate(r); }

  /// transform the path by m
  void transform(const Matrix4& m) { rep->transform(m); }

  /// scale position coords. by s
  void scalePosition(Real s) { rep->scalePosition(s); }


  virtual void serialize(Serializer& s); ///< read or write object state to Serializer

  virtual bool formatSupported(String format, Real version = 1.0, ExternalizationType type = IO) const; ///< query if specific format is supported (for input, output or both)
  virtual void externalize(Externalizer& e, String format = "", Real version = 1.0); ///< read or write object state to Externalizer

protected:
  // virtual initialization methods called by constructors
  virtual void create();
  virtual void create(const Path& p);
  virtual void create(const Point3& sp, const Orient& so, const Point3& ep, const Orient& eo);
  virtual void create(const array<Point3>& points, const array<Orient>& orients, bool deltas);
  virtual void create(const array<Vector>& points, bool deltas);
  virtual void create(const ExpressionVector& p);

  ref<PathRep> rep; ///< representation 
  String frame;     ///< application defined coord. frame specifier
  String units;     ///< application defined unit specifier

  void init(const array<Point3>& points, const array<Orient>& orients, bool deltas); // waypoints init

  // Serialization helpers
  Serializable::SerializableDerivedInstantiator<LineSegPathRep> lineSegPathRepInstantiator;
  Serializable::SerializableDerivedInstantiator<WaypointPathRep> waypointPathRepInstantiator;

  friend class Trajectory;
};


// Operations

inline std::ostream& operator<<(std::ostream& out, const Path& p) // Output
{ return out; }


} // base

#endif

---