cml_trajectory.h

美国COPLEY驱动器,程序开发工具之一.

/************************************************************/
/*                                                          */
/*  Copley Motion Libraries                                 */
/*                                                          */
/*  Author: Stephen Glow                                    */
/*                                                          */
/*  Copyright (c) 2002-2005 Copley Controls Corp.           */
/*                          http://www.copleycontrols.com   */
/*                                                          */
/************************************************************/

/** \file
*/

#ifndef _DEF_INC_TRAJECTORY
#define _DEF_INC_TRAJECTORY

#include "CML_Settings.h"
#include "CML_Error.h"
#include "CML_Utils.h"

CML_NAMESPACE_START()

/***************************************************************************/
/**
Trajectory information class.

One of the control modes supported by the Copley Controls amplifiers is
called interpolated position mode.  This allows complex trajectories to be
generated by the CANopen master controller, and streamed to one or more
amplifiers in real time.  Each point on the trajectory contains three 
pieces of information; Position, Velocity, and Time until the next point.
For this reason, these trajectories are also often called PVT profiles.

The Amp object contains support for streaming a PVT trajectory down to 
the amplifier automatically (see Amp::SendTrajectory).  This virtual class 
provides the interface through which the trajectory data is retrieved by the 
Amp object.

Note that this pure virtual class provides no actual implementation code.
The calculation of the trajectory points is the responsibility of the 
inheriting class.
*/
/***************************************************************************/
class Trajectory
{
public:

   /// Start a new trajectory.  This function is called by Amp::SendTrajectory
   /// before the first call to Trajectory::NextSegment.  It gives the trajectory
   /// object a chance to return an error indicating that it isn't ready to be sent.
   /// @return An error pointer if the trajectory object is not available, or NULL
   ///         if it is ready to be sent.
   virtual const Error *StartNew( void ){ return 0;}

   /// Trajectory finished.  This function is called by the Amp object when it is
   /// finished with the trajectory object and no longer holding a reference to it.
   /// Typically, this will happen after the Trajectory::NextSegment function has 
   /// returned a zero time value, although it can also occure when some external 
   /// event causes the Amp object to abort a running trajectory.
   virtual void Finish( void ){}

   /// This function indicates whether the velocity information returned by 
   /// NextSegment should be used.  If this returns true, then the amplifier 
   /// will operate in PVT mode and use cubic polynomial interpolation between
   /// trajectory segments.  If this returns false, then the velocity returned
   /// by NextSegment will be ignored, and the amplifier will run in PT mode
   /// using linear interpolation between sets of points.
   ///
   /// @return true if velocity information should be used (default), or 
   ///         false if velocities should be ignored.
   virtual bool UseVelocityInfo( void ){ return true; }

   /// Get the next segment of position, velocity & time info.
   /// Note that this function will be called from the high 
   /// priority CANopen receiver task.  Therefore, no lengthy 
   /// processing should be done here.
   ///
   /// @param pos The new position value is returned here.
   ///            This parameter is specified in "user units".  See 
   ///            Amp::SetCountsPerUnit for details.
   ///
   /// @param vel The new velocity value is returned here.
   ///            This parameter is specified in "user units".  See 
   ///            Amp::SetCountsPerUnit for details.
   ///            Note that the velocity data will be ignored if the 
   ///            function UseVelocityInfo() returns false.
   ///            In this case the amplifier will use linear interpolation
   ///            between points.
   ///
   /// @param time The segment time is returned here.  This is
   ///        in milliseconds and ranges from 1 to 255.  If
   ///        zero is returned, this is the last frame in the profile.
   ///
   /// @return An error object.  If this is not Error::OK, then the
   ///         segment data is assumed to be invalid.
   virtual const Error *NextSegment( uunit &pos, uunit &vel, uint8 &time ) = 0;
};


/***************************************************************************/
/**
Linkage trajectory.  This class is similar to the Trajectory class, except
that it is used to pass multi-axis trajectory information to a linkage 
rather then single axis trajectory information to a single amplifier.

Like the base Trajectory class, the base LinkTrajectory class is pure virtual.
This class should be extended by actual trajectory implementations.
*/
/***************************************************************************/
class LinkTrajectory 
{
public:

   /// Start a new trajectory.  This function is called before the first call to 
   /// LinkTrajectory::NextSegment.  It gives the trajectory object a chance to 
   /// return an error indicating that it isn't ready to be sent.
   /// @return An error pointer if the trajectory object is not available, or NULL
   ///         if it is ready to be sent.
   virtual const Error *StartNew( void ){ return 0;}

   /// Trajectory finished.  This function is called by the Linkage object when it is
   /// finished with the trajectory and no longer holding a reference to it.
   /// Typically, this will happen after the LinkTrajectory::NextSegment function has 
   /// returned a zero time value, although it can also occure when some external 
   /// event causes the trajectory to be aborted.
   virtual void Finish( void ){}

   /// Get the dimension of the trajectory.  The trajectory dimension gives the 
   /// number of axes defined for the trajectory.  This can not change from the time
   /// StartNew() is called to the time Finish() is called.  The position and 
   /// velocity arrays passed to NextSegment will be of at least this size.
   /// @return The dimension of the trajectory.
   virtual int GetDim( void ) = 0;

   /// This function indicates whether the velocity information returned by 
   /// NextSegment should be used.  If this returns true, then the amplifier 
   /// will operate in PVT mode and use cubic polynomial interpolation between
   /// trajectory segments.  If this returns false, then the velocity returned
   /// by NextSegment will be ignored, and the amplifier will run in PT mode
   /// using linear interpolation between sets of points.
   ///
   /// @return true if velocity information should be used (default), or 
   ///         false if velocities should be ignored.
   virtual bool UseVelocityInfo( void ){ return true; }

   /// Get the next segment of position, velocity & time info.
   /// Note that this function will be called from the high 
   /// priority CANopen receiver task.  Therefore, no lengthy 
   /// processing should be done here.
   ///
   /// @param pos An array where the position values will be
   ///        returned.  This array will be at least D elements
   ///        long, where D is the trajectory dimension as
   ///        returned by LinkTrajectory::GetDim()
   ///
   /// @param vel An array where the velocity values will be
   ///        returned.  These values are ignored if the function
   ///        UseVelocityInfo() returns false.
   ///
   /// @param time The segment time is returned here.  This is
   ///        in milliseconds and ranges from 1 to 255.  If
   ///        zero is returned, this is the last frame in the profile.
   ///
   /// @return A pointer to an error object on failure, or NULL on success.
   virtual const Error *NextSegment( uunit pos[], uunit vel[], uint8 &time ) = 0;
};

CML_NAMESPACE_END()

#endif