/****************************************************************************

 Package:		SurgicalWorkstation
 
 File:			ImmSurgicalWorkstation.h

 Version:		1.0

 Description:	Provides abstrations for programming the
				Immersion Surgical Workstation.

 Copyright:		(c)2001 Immersion Corporation.  All Rights Reserved.

****************************************************************************/

#ifndef IMMERSION_SURGICALWORKSTATION_IMMSURGICALWORKSTATION_H
#define IMMERSION_SURGICALWORKSTATION_IMMSURGICALWORKSTATION_H

#include <ImmDevice3.h>


#if defined SIMULATOR_DLL_EXPORTS

#define DLL_SYMBOL __declspec(dllexport)

#else

#define DLL_SYMBOL __declspec(dllimport)

#endif





/***************************************************************************/
//
//  ImmSWTool Interface Class Definition
//
/***************************************************************************/
/**
 * The ImmSWTool class is an abstraction of the Surgical Workstation's 
 * Laproscopic haptic interface. This class derives from ImmDevice3 providing 
 * a convenient, uniform interface for haptic research and development. To 
 * instantiate an ImmSWTool object, you cannot use an ordinary constructor; 
 * instead, you must construct its owner, a ImmSurgicalWorksation using the 
 * ImmSurgicalWorksationFactory class.
 *
 * The ImmSWTool class is not thread-safe. You must perform locking and 
 * synchronization on your own.
 *
 * The following describes the general implementation philosophy of the 
 * ImmSWTool class. The Get methods and the Set methods are very lightweight. 
 * They basically read or write to state variables. On the other hand, the 
 * Update method performs significant computation and resource management.  
 * Thus, you should not worry about calling the Get and Set methods often, but 
 * only call Update once per servo loop.
 *
 */



class DLL_SYMBOL ImmSWTool : public ImmDevice3
{
	public:
		/**
		 * Get the handle twist, in radians.
		 *
		 * \param  pHandleTwist points to a double where the method will 
		 * copy handlee twist scalar.
		 * 
		 * \return 
		 *
		 *  0 if successfull.
		 *
         * -1 if the device's internal state needs updating with a call to 
		 * Update.    
		 *
		 * -2 if  pHandleTwist is NULL.
		 * 
		 *
		 */ 

		virtual  int GetHandleTwist( double* pHandleTwist )          = 0;

		/**
		 * Get the handle twist velocity, in radians per second.
		 *
		 * \param  pHandleTwistVel points to a double where the method will 
		 * copy handle twist velocity.
		 *
		 * \return 
		 *
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pHandleTwistVel is NULL.
		 *
		 */


		virtual  int GetHandleTwistVel( double* pHandleTwistVel )     = 0;

		/**
		 * Get the tip twist, in radians.
		 *
		 * \param pTipTwist points to double where the tool's tip twist will 
		 * be copied.
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pTipTwist is NULL.
         *
		 */

		virtual  int GetTipTwist( double* pTipTwist )                 = 0;

		/**
		 * Get the tip twist Velocity, in radians per second.
		 *
		 * \param pTipTwistVel points to a double where the tool's tip
		 * twist will be copied.
		 * 
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pTipTwistVel is NULL.
         *
		 */

		virtual  int GetTipTwistVel( double* pTipTwistVel )              = 0;

		/**
		 * Get the gripper extension. The gripper state is a value ranging from
		 * 0.0 (closed) to 1.0 (open). This range is determined by an automatic 
		 * calibration procedure that is constantly performed as Update is 
		 * called. To reset the automatic calibration, call Calibrate (which also 
		 * resets the kinematic calibration).
		 *
		 * \param pGrippers points to a double where the class' gripper extension
		 * value will be copied.
		 * 
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pGrippers is NULL.
		 *
		 */

		virtual  int GetGrippers( double* pGrippers )                 = 0;
		/**
		 * Get the raw gripper encoder value. The raw encoder values range between
		 * a minimum and a maximum value. Although this minimum and maximum values 
		 * will be different in different devices.
		 *
		 * \param pRawGrippers points to an int where the class' raw gripper encoder
		 * value will be copied.
		 * 
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pGrippers is NULL.
		 *
		 */
		virtual int GetRawGrippers(int *pRawGrippers) =0;


		/**
		 * Get the tool's gimbal pitch angle in radians.
		 *
		 * \param pPitch points to a double where the tool's pitch value
		 * will be copied.
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pPitch is NULL.
		 *
		 */

		virtual  int GetPitch( double* pPitch )                       = 0;
		
		/**
		 * Get the yaw angle of the too's gimbal, in radians.
		 *
		 * \param pYaw points to a double where the gimbal's yaw angle will be 
		 * copied.
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pYaw is NULL.
		 *
		 */

		virtual  int GetYaw( double* pYaw )                           = 0;

		/**
		 * Get the tool's insertion depth, in mm.
		 *
		 * \param pDepth points to memory where the tool's insertion depth will
		 * be copied.
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pDepth is NULL.
		 *
		 */

		virtual  int GetInsertionDepth( double* pDepth )              = 0;

		/**
		 * Sets a Cartesian torque command vector (moment) for the endpoint of 
		 * the tool. For safety reasons, the command torque is initialized to zero. 
		 * The X-component corresponds to a torque around the X-axis, the 
		 * Y-component corresponds to a torque around the Y-axis, and the 
		 * Z-component corresponds to a torque around the Z-axis.
		 *
		 * \param pMoment points to an ImmCoord3, a three vector which specifies
		 * the moment to apply to the tool's end-effector.
		 *
		 *
		 * \return 
		 * 
		 *  0 if successfull.
		 *
		 * -1 if the device state needs updating with a call to Update.
		 *
		 * -2 if  pMoment is NULL.
		 *
		 */
		
		virtual  int SetMoment( ImmCoord3* pMoment )                  = 0;
		
		/**
		 * Applies a torque, in mNm, to directly twist the handle of the tool.
		 * This torque is in addition to any torque created due to an applied 
		 * moment. For safety reasons, the torque is initialized to zero. Must
         * call update before this torque will be reflected in the hardware.
         *
		 * 
		 * \param twistTorque species the torque to be applied to the tool's
		 * handle.
		 *
		 * \return Always returns 0.
		 *
		 */

		virtual  int SetHandleTwistTorque( double twistTorque )       = 0;


		/**
		 * Applies a torque, in mNm, to the grippers of the tool to open or 
		 * close the grippers. For safety reasons, the torque is initialized 
		 * to zero.
		 * 
		 * \param gripTorque specifies the scalar values of the torque
		 * to be applied to the tool's gripper. The magnitude will be
		 * trincated to a maximum value of 1736.
		 * 
		 * \return Always returns 0.
		 *
		 */

		virtual  int SetGripTorque( double gripTorque )               = 0;

		
		/**
		 * Describes the shape of the tool's tip by specifying its length and  
		 * offset. This affects the value returned by GetPosition. The length
		 * is how far the tip extends above or below the end of the shaft and 
		 * offset describes how far the tip sticks out from the side of the 
		 * shaft at a right angle. Both of these values are in millimeters.
		 *
		 * \param length specifies the length of the tool tip, in millimeters. 
		 * If the tip extends above the end of the shaft, pass a negative value. 
		 *
		 * \param offset specifies how far the tip extends out along a right 
		 * angle to the tool tip, in millimeters. 
		 *
		 *
		 * \return Always returns 0.
		 *
		 */

		virtual  int SetTipParameters( double length, double offset ) = 0;

		/**
		 * Get a copy the tool's tip parameters.
		 *
		 * \param length points to a double. The parameter specifies the extent
		 *  to which the virtual tool tip length extends beyond the mechanical tool,
		 *  along the logitudinal axis. The length is measured in mm.
		 * 
		 * \param offset points to a double. The parameter specifies the extent
		 * to which the virtual tool tip is offset perpendicular to the longitudinal
		 * axis of the mechanical tool. . The offset is measured in mm.
		 *
		 * \return 
		 *
		 * 0 if successfull.
		 *
		 * -1 if the device state needs updating
		 *
		 * -2 if either one of the parameters points to null mememory.
		 *
		 */

		virtual  int GetTipParameters( double * length, double * offset ) = 0;

protected:
	// The constructor/destructor are protected because you have
	// to create a ImmSWTool with ImmSurgicalWorkstationFactory
	ImmSWTool()				{}
	virtual ~ImmSWTool()	{}
};


/***************************************************************************/
//
//  ImmSWToolJS Interface Class Definition
//
/***************************************************************************/
/**
 * The ImmSWToolJS class is new level of abstraction introduced to include
 * the additional functionality of direct joint moment/force control of the
 * Surgical Workstation's  Laproscopic haptic interface. 
 * This class derives from ImmSWTool.
 * The ImmSWToolJS class is not thread-safe. You must perform locking and 
 * synchronization on your own.
 * The following describes the general implementation philosophy of the 
 * ImmSWToolJS class. The Set methods are very lightweight. They basically 
 * write to state variables. You do not need to call the update method after 
 * calling these methods.
 * Calling the SetMoment and SetForce methods of the ImmSWTool class overwrites 
 * the values set by these methods. Also when you call the Set methods of this 
 * class, only the force/moment value of that particular joint in written.
 *
 */
class DLL_SYMBOL ImmSWToolJS : public ImmSWTool
{
public:
		/**
		* Set the torque in mNm for the Yaw axis. This value is immediately reflected 
		* in the hardware
		*/
		virtual int SetYawTorque (double yaw_torque)		= 0;

		/**
		* Set the torque in mNm for the Pitch axis. This value is immediately reflected 
		* in the hardware
		*/		virtual int SetPitchTorque (double pitch_torque)	= 0;

		/**
		* Set the force in N for the insertion link of the Laparoscopic haptic interafce. 
		* This value is immediately reflected in the hardware.
		*/
		virtual int SetInsertionForce (double axial_force)		= 0;

protected:
	ImmSWToolJS()			{}
	virtual ~ImmSWToolJS()	{}
};

/***************************************************************************/
//
//  ImmSWCamera Interface Class Definition
//
/***************************************************************************/

/**
 * The ImmSWCamera class is an abstraction of the Surgical Workstation's 
 * camera. This class derives from ImmDevice3 providing a convenient, 
 * uniform interface for haptic research and development. To 
 * instantiate an ImmSWTool object, you cannot use an ordinary constructor; 
 * instead, you must construct its owner, a ImmSurgicalWorksation using the 
 * ImmSurgicalWorksationFactory class.
 *
 * The ImmSWCamera class is not thread-safe. You must perform locking and 
 * synchronization on your own.
 *
 * The following describes the general implementation philosophy of the 
 * ImmSWCamera class. The Get methods and the Set methods are very lightweight. 
 * They basically read or write to state variables. On the other hand, the 
 * Update method performs significant computation and resource management.  
 * Thus, you should not worry about calling the Get and Set methods often, but 
 * only call Update once per servo loop.
 *
 */

class DLL_SYMBOL ImmSWCamera : public ImmDevice3
{
	public:

	/**
	 * Get the lens twist, in radians.
	 *
	 * \param  pLensTwist points to a double where the method will 
	 * copy lense twist scalar.
	 *
	 * \return 
	 *
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pLensTwist is NULL.
	 *
	 */ 

	virtual  int GetLensTwist( double* pLensTwist )          = 0;

	/**
	 * Get the lens twist velocity. Currently unsupported.
	 *
	 * \param  pLensTwistVel points to a double where the method will 
	 * copy lense twist scalar.
	 *
	 * \return 
	 *
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pLensTwistVel is NULL.
	 *
	 */

	virtual  int GetLensTwistVel( double* pLensTwistVel )    = 0;

	/**
	 * Get the CCD Twist, in radians.
	 *
	 * \param pCCDTwist points double where the mesured CCD Twist scalar
	 * will be copied into.
	 *
	 * \return 
	 * 
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pCCDTwist is NULL.
     *
	 */

	virtual  int GetCCDTwist( double* pCCDTwist )            = 0;

	/**
	 * Get the CCD Twist Velocity, in radians per second.
	 *
	 * \param pCCDTwistVel points to memory into which the CCD Twist velocity 
	 * (scalar) will be copied.
	 *
	 * \return 
	 * 
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pCCDTwistVel is NULL.
	 *
	 *
	 */

	virtual  int GetCCDTwistVel( double* pCCDTwistVel )      = 0;

	/**
	 * Get the camera's pitch, in radians.
	 *
	 * \param pPitch points to a double where the camera's scalar pitch 
	 * value will be copied.
	 *
	 * \return 
	 *
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pPitch is NULL.
	 *
	 */

	virtual  int GetPitch( double* pPitch )                  = 0;

	/**
	 * Get the camera's yaw, in radians.
	 *
	 * \param pYaw points to a double where the camera's yaw value will be 
	 * copied.
	 * 
	 * \return 
	 * 
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pYaw is NULL.
	 *
	 */

	virtual  int GetYaw( double* pYaw )                      = 0;

	/**
	 * Get the camera's insertion depth, in mm.
	 *
	 * \param pDepth points to a double where the camera's insertion depth 
	 * value will be copied.
	 *
	 * \return 
	 *  
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pDepth is NULL.
	 *
	 */

	virtual  int GetInsertionDepth( double* pDepth )         = 0;

	/**
	 * Establish the camera's position in the world frame (the table).
	 * 
	 * \param pPosition points to the an i-j-k three vector, in ImmCoord3
	 * format, specifying the camera's table position.
	 *
	 * \return 
	 *
	 * 0 if successfull.
	 *
	 * -1 if the device state needs updating.
	 *
	 * -2 if  pPosition is NULL.
	 *
	 */

	virtual  int SetTablePosition( ImmCoord3* pPosition )    = 0;

	/**
	 * Set the table angle, in radians.
	 *
	 * \param radians specifies the table angle, in radian format.
	 *
	 * \return Always returns 0.
	 *
	 */
	virtual  int SetTableAngle( double radians )             = 0;

	/**
	 * Set the camera lens' camber, in radians.
	 *
	 * \param radians specifies the lens' camber.
	 *
	 * \return Always returns 0.
	 */
	virtual  int SetLensCamber( double radians )             = 0;
	
protected:
	// The constructor/destructor are protected because you have
	// to create a ImmSWCamera with ImmSurgicalWorkstationFactory
	ImmSWCamera()			{}
	virtual ~ImmSWCamera()	{}
};



/***************************************************************************/
//
//  ImmSWCamera Class Factory Definition
//
/***************************************************************************/

class DLL_SYMBOL ImmSWCameraFactory
{
	public:
		/**
		 * Acquires a Surgical Workstation Camera
		 *
		 * \param port = (0,1,2,3,4) --> (auto-detect, COM1, COM2, COM3, COM4)
		 *
		 * \param baud = (9600L, 14400L, 38400L, 57600L, 115200L) 
		 * If port = 0, it will try to auto-detect
		 * 
		 * \return The method returns NULL pointer if a device is not found,
		 * otherwise it returns a pointer to the constructed camera interface.
		 *
		 */

		static  ImmSWCamera* AcquireSWCamera( int port, long baud );


		/**
		 * Release the ImmSWCamera acquired with AcquireSWCamera.
		 *
		 * \param pSWCamera points to the acquired camera device, whose
		 * memory will be freed by the camera. The calling method should
		 * be sure to reset the input pointer to NULL.
		 *
		 */

		static void ReleaseSWCamera( ImmSWCamera* pSWCamera );
};



/***************************************************************************/
//
//  ImmSurgicalWorkstation Class Definition
//
/***************************************************************************/

/**
 * The ImmSurgicalWorkstation class is a software abstraction of Immersion's 
 * Surgical Workstation haptic interface device. To instantiate an 
 * ImmSurgicalWorkstation object, you cannot use an ordinary constructor; 
 * instead, you must use the ImmSurgicalWorkstationFactory class.
 *
 * The ImmSurgicalWorkstation class is not thread-safe.  You must perform 
 * locking and synchronization on your own.
 *
 * The following describes the general implementation philosophy of the 
 * ImmSurgicalWorkstation class. The Get methods and the Set methods are very
 * lightweight. They basically read or write to state variables. On the other 
 * hand, the Update method performs significant computation and resource 
 * management. Thus, you should not worry about calling the Get and Set methods 
 * often, but only call Update once per servo loop.
 *
 * The constituent classes of ImmSurgicalWorkstation (the ImmSWTool and 
 * ImmSWCamera) have their own Calibrate and Update methods. These are present 
 * for compliance with their respective interfaces. For efficiency, you should 
 * only call Update and Calibrate of the ImmSurgicalWorkstation.
 *
 */


class DLL_SYMBOL ImmSurgicalWorkstation
{
	// Public Methods
	public:
		/**
		 * Get the Device name
		 *
		 * \return A pointer to a string contain the device's name, and returns
		 * a NULL pointer if the method fails.
		 *
		 */

		virtual char * GetDeviceName( void )  const      = 0;
		
		/**
		 * Initiates a calibration procedure for the Surgical Workstation. 
		 * This must be performed before you can use the device.   
         *
		 * The constituent classes of ImmSurgicalWorkstation (the ImmSWTool 
		 * and ImmSWCamera) have their own Calibrate methods. These are present
		 * for compliance with their respective interfaces. For efficiency, 
		 * you should only call Calibrate of the ImmSurgicalWorkstation.
		 *
		 * \return 
		 * 
		 * 0 if successful
		 *
		 * -3 if it one of its constituent devices is unsupported in hardware.
		 *
		 */

		virtual int    Calibrate()                       = 0;
		
		/**
		 * Updates the stored state of the ImmSurgicalWorkstation. This must be
		 * called in order to get fresh values from its constituent classes' 
		 * GetPosition, GetVelocity, GetGrippers, and GetOrientation. In addition, 
		 * Update modifies the torques applied to the devices, which are dependent 
		 * on the device's joint configuration. 
         *
		 * The constituent classes of ImmSurgicalWorkstation (the ImmSWTool and 
		 * ImmSWCamera) have their own Update methods. These are present for compliance 
		 * with their respective interfaces. For efficiency, you should only call Update 
		 * of the ImmSurgicalWorkstation.
         *
		 * For laparoscopy devices which support a heartbeat, the update method method 
		 * be called at a nominal frequency of 50 Hz, and no less fequently than 30 Hz.
		 * Should the device fail to receive a heartbeat signal from the API, it will
		 * transition to a dormant state, where no forces will be rendered through the
		 * robot. Presently, the API does not support a call which will indicate if the
		 * robot is in a domant state. To transition the device from a dormant state to
		 * an active one, call the WakeUp method.
		 * 
		 * \return 
		 *
		 * 0 if successful, 
		 *
		 * -3 if one of its constituent devices is unsupported in hardware.
		 *
		 */


		virtual int    Update()                          = 0;

		/**
		 * Get access to the left tool's interface.
		 *
		 * \return 
		 *
		 * A pointer to a ImmSWTool interface for the left tool. 
		 *
		 * A NULL pointer if the method fails.
		 *
		 */
		virtual ImmSWTool *  GetLeftTool()               = 0;

		/**
		 * Get access to the right tool's interface.
		 *
		 * \return 
		 *
		 * A pointer to a ImmSWTool interface for the right tool. 
		 *
		 * A NULL pointer if the method fails.
		 *
		 */

		virtual ImmSWTool *	 GetRightTool()              = 0;

		/**
		 * Get access to the camera's interface.
		 *
		 * \return 
		 *
		 * A pointer to a ImmSWCamera interface for the workstation's
		 * camera. 
		 * 
		 * A NULL pointer if the method fails.
		 *
		 */

		virtual ImmSWCamera * GetCamera()                = 0;

		/**
		 * Send a wake-up signale to the devices.
		 *
		 */
		virtual  void	WakeUp()                         = 0;

		/**
		 * Determine if the device is in a suspend mode. In the present 
		 * implentation, the surgical workstation will be suspended if the
		 * camera's button has been pressed.
		 *
		 * \return The method returns true if there is a suspend signal.
		 *
		 */
		virtual  bool  GetIsSuspended()                  = 0;

	protected:
		// The constructor/destructor are protected because you have
		// to create a ImmSurgicalWorkstation with ImmSurgicalWorkstationFactory
		ImmSurgicalWorkstation()			{}

		virtual ~ImmSurgicalWorkstation()	{}
};



/**
 * The ImmSurgicalWorkstationFactory class is responsible for creating and 
 * destroying ImmSurgicalWorkstation objects. It is entirely composed of static 
 * methods. There is an AcquireSW method for each kind of interface.  There is 
 * a single Release method for destroying previously acquired 
 * ImmSurgicalWorkstation objects.
 *
 * The ImmSurgicalWorkstationFactory class is not thread-safe. You must perform 
 * locking and synchronization on your own.
 *
 */

class DLL_SYMBOL ImmSurgicalWorkstationFactory
{
	public:
		/**
		 * Acquires a Surgical Workstation
		 *
		 * \return A pointer to an ImmSurgicalWorkstation interface. It returns
		 * a NULL pointer if the method fails.
		 *
		 */

		static  ImmSurgicalWorkstation* AcquireSW();

		/**
		 * Releases the acquired Surgical Workstation
		 *
		 * \param pSW points to a surgical workstaion acquired from the
		 * AcquireSW method.
		 *
		 */
		static  void ReleaseSW( ImmSurgicalWorkstation* pSW );
};


#endif	// IMMERSION_SURGICALWORKSTATION_IMMSURGICALWORKSTATION_H