PCM Simulation Library
=========================
Documentation for PCM Simulation Interface

Created and maintained by
	Daniel Santos <dsantos@stanford.edu>

=========================
Interface to DE and Simulation
=========================

	The PCM is interfaced to the rest of the simulation through a simple
PCM text file (e.g. robot1.pcm ).  The text file has the following format:

---Beginning of File---
# Commented lines begin with the # symbol
# Provide a brief description of what this .pcm file is for

# Define the contact types that will be used
# Each line begins with the "ContactType" type-specifier
#   followed by a name for that contact type and then
#   followed by what PCM ContactType to use and with what parameters
#   ContactType NAME = PCMContactType [{ Parameter1 = XX, Parameter2 = XX }];

ContactType Contact1 = GenericAContact [{ Angle = 3.14159/2 }];
ContactType Contact2 = GenericAContact [{ Angle = 3.14159/4 }];

# Define what surface and object pairs will be used with what contacts
# Each line begins with either the "SurfacePair" or "ObjectPair" identifier
#   followed by a surface/object, *, surface/object, -> Contact
#   SurfacePair NAME * NAME -> NAME;

SurfacePair SurfaceA * SurfaceB -> Contact1;
# When SurfaceA and SurfaceB come into contact create a Contact1
#  where Contact1 was defined earlier by a ContactType line
SurfacePair SurfaceA * SurfaceC -> Contact2;

ObjectPair ObjectA * ObjectB -> Contact1;

# Note - ObjectPairs override SurfacePair declarations
#        Names of Surfaces and Objects must correspond to the names
#          of Surfaces and Objects defined in the CDL
---End of File---

See Also "example.pcm" for an example of a .pcm file

=========================
=========================
Description of Contact Types
=========================
=========================

**************
DefaultContact
**************

	DefaultContact is the contact that the PCM creates between two
objects if no ContactType has been specified.  DefaultContact provides a
file template for the creation of PCM Contacts.  New contact models can be
written by copying and re-naming DefaultContact.cc and DefaultContact.hh
and changing the "guts" where prompted in DefaultContact.cc and
DefaultContact.hh.  DefaultContact, as well as all contacts, provides methods
to query the current state of the contact (such as orientation).
   
  Parameters:
	NONE

***************
GenericAContact
***************

	GenericAContact is a simple contact model.  Upon physical contact
detection by DE, a point constraint is created.  The point constraint acts 
like a "ball and socket" joint.  In DE, a point in ObjectA's Frame and a point
in ObjectB's Frame are forced to be coincident.  The point of constraint is
defined as the origin of ObjectA's Frame.  Thus, a typical implementation
would be to define ObjectA as the Foot and ObjectB as the floor.  At the
instant of contact, the relative orientation of ObjectA wrt ObjectB is stored.
When the relative orientation changes by some user-specified Angle,
(comparison done using axis/angle representation), the point constraint is
destroyed and the contact is "released".  A new GenericAContact will not be
created while the objects remain in physical contact.  This means that the
objects must seperate and then remake contact for a new GenericAContact to be
formed.

  Parameters:
	Angle - in radians

***************
GenericBContact
***************

	GenericBContact is a simple contact model.  Upon physical contact
detection by DE, a point constraint is created.  The point constraint acts 
like a "ball and socket" joint.  In DE, a point in ObjectA's Frame and a point
in ObjectB's Frame are forced to be coincident.  The point of constraint is
defined as the origin of ObjectA's Frame.  Thus, a typical implementation
would be to define ObjectA as the Foot and ObjectB as the floor.
GenericBContact differs from GenericAContact in its termination condition.  In
GenericBContact, the point constraint is destroyed whenever ObjectA's Frame
wrt ObjectB's Frame exceeds some rotation specified by Angle (user parameter).
GenericBContact does not look at the relative change from when contact was
created.  It only looks at the current orientation without regard to when/how
the objects came into contact.  Thus, the initial specification of ObjectA's 
Frame and ObjectB's Frame is important.  Comparison is again done using
axis/angle representation.  GenericBContact does not require ObjectA and
ObjectB to physically separate before creating a new GenericBContact

  Parameters:
	Angle - in radians