End User Description: DtRailMovementUpdater provides a kinematics-based model of an *entity moving along a generated path or route in a fashion where it is locked onto the the path. More...

Public Member Functions
	DtRailMovementUpdater (DtRailMovementController parentController, bool useTurnSmoothing, bool useAcceleration, bool useHighGroundClamp, const DtAttachedTerrain attachedTerrain)
	Pass in the parent controller so we have access to our path and where we are in our path.
virtual	~DtRailMovementUpdater ()
	destructor
virtual bool	init ()
virtual void	clear ()
virtual void	setEntityState (DtVrfMovingObjectStateRepository *state)
virtual double	setUpTurn (DtRailSegment currentSeg, DtRailSegment nextSeg, const int currentLane, const int drivingLane, double headingDiff, bool useLocalPos=false, DtVector currentLocalPos=DtVector::zero())
	Sets up the next turn.
virtual bool	turnValid (int currentLane)
	We need to check if the turn we calculated is still valid.
virtual bool	recalculateTurnSpline (DtRailSegment currentSeg, DtRailSegment nextSeg, const int currentLane, const int passingLane)
virtual bool	modifyTurnSpline (const DtVector &currentLocalPos, const DtRailSegment currentSegment, const DtRailSegment nextSegment, const int currentLane, const int passingLane)
	Modifies the exsiting turn spline.
virtual void	setUpLaneSwitch (const DtVector &projectedLocation, DtRailSegment *currentSeg, const int currentLane, const int passingLane)
	Sets up a switch splice for switching lanes form currentLane to desiredLane.
virtual void	update (DtRailSegment currentSeg, DtRailSegment nextSeg, double drivingSpeed, int passingLane, DtTime simTime=0.0)
	Calculate new kinematic state and update our state repository.
virtual void	updateNoMovement ()
	Sets the movement state of the entity to stopped. Call in place of update().
virtual void	updateFromPSR (const DtVector localPos, DtRailSegment *currentSeg)
	If loading in from a scenario saved out during a rail task, chances are the entity is not at the start of rail so update from it's saved location on the current segment.
virtual const DtCoordTransform &	localToBodyTransform () const
	set/get the turn entry and exit points.
Protected Member Functions
virtual void	useFuel (double fuelUsed)
	Upone reaching a new segment our coordinate transform matrices will be recomputed.
virtual bool	checkEntityImmobilized ()
virtual double	fuelLeft () const
	Looks up the resource named �fuel� in the entity�s Resource Manager.
virtual void	updateRepository (const DtVector &localPosition, const DtVector &localVelocity, const DtVector &localAcceleration, const DtTaitBryan &localOrientation, const DtVector &rotationalVelocity, double newHeading)
	Updates the local state repository: It places the position, velocity, acceleration, and orientation arguments into the local repository.
virtual double	calculateAcceleration (double desiredSpeed)
virtual void	calculateOrientationAndPosition (const DtVector &newLocalProjectedLocation, double newHeading, DtDcm &newLocalOrientation, DtVector &newLocalPosition)
	Calculates the orientation and position of the entity, given a new location and heading.
bool	groundClamp (double heading, const DtVector &location, DtAttachedTerrain &terrain, DtVector &newNormal)
	Clamps the entity to the ground at the specified location, and determines the normal of the plane the entity is on at that location.
void	groundClampHighFidelity (double heading, const DtVector &location, DtAttachedTerrain &terrain, DtVector &newNormal)
	Uses all four ground interaction points to determine the plane of the entity and the soil type.
void	groundClampLowFidelity (double heading, const DtVector &location, DtAttachedTerrain &terrain, DtVector &newNormal)
	Uses only the center ground interaction point.
virtual DtVector	calculateRotationalVelocity (const DtTaitBryan &newTopoOrientation, const DtTaitBryan &oldTopoOrientation, double dT)
	Calculates rotational velocity from new and old topocentric orientation.
virtual void	calculateDirectionOfLinearMotion (const DtDcm &newLocalOrientation, const DtVector &newLocalPosition, DtDcm &newLocalDirectionOfLinearMotion)
	Computes direction of linear motion.
virtual DtVector	calculateBodyAcceleration (double desiredSpeed, const DtVector &oldBodyVelocity, double dT)
	Calculates the linear acceleration in body coordinates of the entity in meters/second/second.
virtual DtVector	calculateBodyVelocity (const DtVector &oldBodyVelocity, const DtVector &newBodyAcceleration, double dT)
virtual DtVector	calculateProjectedLocation (const DtVector &oldLocalPosition, const DtVector &newBodyAcceleration, const DtVector &oldBodyVelocity, const DtVector &newBodyVelocity, double newHeading)
virtual bool	rotationalVelocityShouldBeClamped (const DtVector &bodyRotationalVelocity)
	Returns true if given magnitude of body rotational velocity is < 0.0001 radians/sec, false otherwise.
virtual bool	passedTurnPoint (double distSq, double &differance)
	Determines if the entity has gone passed the point at which it should start to turn.
virtual DtVector	determinePositionAlongNextSegment (DtRailSegment *nextSegment, double distance, double &newHeading, int lanePos, DtVector projectedPos)
	When the entity moves past the end point of it's current segment, the remaining distance traveled is then applied along the next segment to determine where the entity is on the segment.
virtual void	determinePosition (const DtRailSegment *currentSeg, const double distSq, const int currentLane, DtVector &newLocalProjectedLocation)
	Get position relative to lane along segment.
Protected Attributes
DtRailMovementController *	myController
DtVrfMovingObjectStateRepository *	myMovingStateRep
const DtAttachedTerrain *	myAttachedTerrain
	Used to ground clamp the entity-- TODO how we ground clamp, ie get access to terrain may change, we might want to instead just point to the physical world.
DtCoordTransform	myCoordTransform
bool	myUseHighFidelityGroundClamping
	Only calculate these when switching rails, expensive.
bool	myUseAcceleration
bool	myUseTurnSmoothing
double	myDistanceSqToTurn
	This is the distance from the current segment's startpoint to the turn point on the segment.
double	myHeadingDiff
	Difference between our current segment's heading and our next segment.
DtRailSplineCalculator	myTurnSpline
	Handles turning from one rail to another using a quadratic spline curve.
DtRailSplineCalculator	myLaneSwitchSpline
	Handles switching lanes on the same rail using a quadratic spline curve.
double	myTurnDistTraveled
	This is the distance the entity has traveled so far.
double	myDistAlongSeg
Private Member Functions
	DtRailMovementUpdater ()
	Default constructor; not implemented.
	DtRailMovementUpdater (const DtRailMovementUpdater &orig)
	Copy constructor; not implemented.
const DtRailMovementUpdater &	operator= (const DtRailMovementUpdater &orig)
	assignment operator; not implemented

Detailed Description

End User Description: DtRailMovementUpdater provides a kinematics-based model of an *entity moving along a generated path or route in a fashion where it is locked onto the the path.

DtRailSegment is the class that represents the segmentof the path which has various attributes which will help the entity determine how it will follow along the segment such as the speed and heading the entity will follow along the segment. It converts throttle and brake into orientation, acceleration, velocity, and position.

Uses Descriptor Type: DtComponentDescriptor

Constructor & Destructor Documentation

DtRailMovementUpdater::DtRailMovementUpdater	(	DtRailMovementController *	parentController,
		bool	useTurnSmoothing,
		bool	useAcceleration,
		bool	useHighGroundClamp,
		const DtAttachedTerrain *	attachedTerrain
	)

Pass in the parent controller so we have access to our path and where we are in our path.

virtual DtRailMovementUpdater::~DtRailMovementUpdater ( ) [virtual]

destructor

DtRailMovementUpdater::DtRailMovementUpdater ( ) [private]

Default constructor; not implemented.

DtRailMovementUpdater::DtRailMovementUpdater ( const DtRailMovementUpdater & orig ) [private]

Copy constructor; not implemented.

Member Function Documentation

virtual bool DtRailMovementUpdater::init ( ) [virtual]

virtual void DtRailMovementUpdater::clear ( ) [virtual]

virtual void DtRailMovementUpdater::setEntityState ( DtVrfMovingObjectStateRepository * state ) [virtual]

virtual double DtRailMovementUpdater::setUpTurn	(	DtRailSegment *	currentSeg,
		DtRailSegment *	nextSeg,
		const int	currentLane,
		const int	drivingLane,
		double	headingDiff,
		bool	useLocalPos = `false`,
		DtVector	currentLocalPos = `DtVector::zero()`
	)		`[virtual]`

Sets up the next turn.

If using turn smoothing will call calculateTurnPath. If not, just sets the entry and exit turn points to the end of the current segment providing for the lane offsets of the 2 lanes. Returns the distance squared from the start of the segment to the turn point.

virtual bool DtRailMovementUpdater::turnValid ( int currentLane ) [virtual]

We need to check if the turn we calculated is still valid.

If our current lane is the same as the entry lane no need to recalculate the turn.

virtual bool DtRailMovementUpdater::recalculateTurnSpline	(	DtRailSegment *	currentSeg,
		DtRailSegment *	nextSeg,
		const int	currentLane,
		const int	passingLane
	)		`[virtual]`

virtual bool DtRailMovementUpdater::modifyTurnSpline	(	const DtVector &	currentLocalPos,
		const DtRailSegment *	currentSegment,
		const DtRailSegment *	nextSegment,
		const int	currentLane,
		const int	passingLane
	)		`[virtual]`

Modifies the exsiting turn spline.

Returns true if possible to modify the spline, false if the entity is too far along the spline to modify it reliably

virtual void DtRailMovementUpdater::setUpLaneSwitch	(	const DtVector &	projectedLocation,
		DtRailSegment *	currentSeg,
		const int	currentLane,
		const int	passingLane
	)		`[virtual]`

Sets up a switch splice for switching lanes form currentLane to desiredLane.

virtual void DtRailMovementUpdater::update	(	DtRailSegment *	currentSeg,
		DtRailSegment *	nextSeg,
		double	drivingSpeed,
		int	passingLane,
		DtTime	simTime = `0.0`
	)		`[virtual]`

Calculate new kinematic state and update our state repository.

virtual void DtRailMovementUpdater::updateNoMovement ( ) [virtual]

Sets the movement state of the entity to stopped. Call in place of update().

virtual void DtRailMovementUpdater::updateFromPSR	(	const DtVector	localPos,
		DtRailSegment *	currentSeg
	)		`[virtual]`

If loading in from a scenario saved out during a rail task, chances are the entity is not at the start of rail so update from it's saved location on the current segment.

virtual const DtCoordTransform& DtRailMovementUpdater::localToBodyTransform ( ) const [virtual]

set/get the turn entry and exit points.

These will be computed initially when an entity moves on to a new segment, however cases could arise where the user may want to manipulate these Used to tranform local to body reference coordinate system based on the current segment's heading and using the end point as the offset. Makes computations much easier. Recomputed when switching to next segment in the setUpTurn function.

virtual void DtRailMovementUpdater::useFuel ( double fuelUsed ) [protected, virtual]

Upone reaching a new segment our coordinate transform matrices will be recomputed.

Looks up the resource named �fuel� in the entity�s Resource Manager. If the resource is not found, useFuel() just returns. If the resource is found, the amount of fuel passed as the argument to useFuel() is deducted from the resource. When the resource reaches 0, a warning is printed (using DtWarn).

Parameters:

fuelUsed Amount of fuel to deplete.

virtual bool DtRailMovementUpdater::checkEntityImmobilized ( ) [protected, virtual]

virtual double DtRailMovementUpdater::fuelLeft ( ) const [protected, virtual]

Looks up the resource named �fuel� in the entity�s Resource Manager.

If the resource is not found, it returns an appropriately large constant to implement unlimited fuel. Otherwise, the value of the resource is returned.

Returns:: Amount of fuel resource still available.

virtual void DtRailMovementUpdater::updateRepository	(	const DtVector &	localPosition,
		const DtVector &	localVelocity,
		const DtVector &	localAcceleration,
		const DtTaitBryan &	localOrientation,
		const DtVector &	rotationalVelocity,
		double	newHeading
	)		`[protected, virtual]`

Updates the local state repository: It places the position, velocity, acceleration, and orientation arguments into the local repository.

It puts the heading into the repository. It calculates the current speed from the velocity vector passed and sets that value in the local repository. It calculates the distance traveled this frame (speed * dT) and uses that and the fuel consumption ground vehicle parameter to determine the fuel used, and then calls useFuel().

Parameters:

localPosition	Position in local (database) coordinates in meters.
localVelocity	Velocity in local (database) coordinates in meters/second.
localVelocity	Velocity in local (database) coordinates in meters/second/second.
localOrientation	Local orientation of entity in radians.
rotationalVelocity	In radians/second.
newHeading	In radians.

virtual double DtRailMovementUpdater::calculateAcceleration ( double desiredSpeed ) [protected, virtual]

Returns:: The acceleration resulting from the internal engine systems of this entity. Result is signed, with positive being body-forward acceleration and negative body-reverse.

virtual void DtRailMovementUpdater::calculateOrientationAndPosition	(	const DtVector &	newLocalProjectedLocation,
		double	newHeading,
		DtDcm &	newLocalOrientation,
		DtVector &	newLocalPosition
	)		`[protected, virtual]`

Calculates the orientation and position of the entity, given a new location and heading.

Checks for intersections with the terrain, to determine altitude and orientation (from support points) from 1/4 of the height of the entity's bounding volume as a rough approximation of the entity's wheel's or tread (or knees).

Returns:: nothing, but sets the specified orientation and position appropriately.

Note:: As a side effect, this also fills in the soil type, position, and altitude information of the groundCenter of the vrfObject. This is done through the placePoints() call from the state repository.

bool DtRailMovementUpdater::groundClamp	(	double	heading,
		const DtVector &	location,
		DtAttachedTerrain &	terrain,
		DtVector &	newNormal
	)		`[protected]`

Clamps the entity to the ground at the specified location, and determines the normal of the plane the entity is on at that location.

Returns:: a boolean indicating success or failure in performing the ground clamping and determining the new normal.

Note:: As a side effect of this function, the soil type in the center ground interaction point is set.

The type of ground clamping also depends on the entity's configuration. Either high or low fidelity ground clamping is performed as specified.

See also:: groundClampHighFidelity; groundClampLowFidelity

void DtRailMovementUpdater::groundClampHighFidelity	(	double	heading,
		const DtVector &	location,
		DtAttachedTerrain &	terrain,
		DtVector &	newNormal
	)		`[protected]`

Uses all four ground interaction points to determine the plane of the entity and the soil type.

The left, right, and other support points are used to determine the plane, and the returned normal is the normal to that plane.

void DtRailMovementUpdater::groundClampLowFidelity	(	double	heading,
		const DtVector &	location,
		DtAttachedTerrain &	terrain,
		DtVector &	newNormal
	)		`[protected]`

Uses only the center ground interaction point.

The normal is the normal of the polygon on which the center point sits. And the soil type is also the polygon's. This requires fewer intersection tests with the terrain, but also may return an incorrect normal if the entity is sitting across several polygons.

virtual DtVector DtRailMovementUpdater::calculateRotationalVelocity	(	const DtTaitBryan &	newTopoOrientation,
		const DtTaitBryan &	oldTopoOrientation,
		double	dT
	)		`[protected, virtual]`

Calculates rotational velocity from new and old topocentric orientation.

virtual void DtRailMovementUpdater::calculateDirectionOfLinearMotion	(	const DtDcm &	newLocalOrientation,
		const DtVector &	newLocalPosition,
		DtDcm &	newLocalDirectionOfLinearMotion
	)		`[protected, virtual]`

Computes direction of linear motion.

In base class, this is equivalent to newLocalOrientation, so it sets newLocalDirectionOfLinearMotion = newLocalOrientation.

virtual DtVector DtRailMovementUpdater::calculateBodyAcceleration	(	double	desiredSpeed,
		const DtVector &	oldBodyVelocity,
		double	dT
	)		`[protected, virtual]`

Calculates the linear acceleration in body coordinates of the entity in meters/second/second.

virtual DtVector DtRailMovementUpdater::calculateBodyVelocity	(	const DtVector &	oldBodyVelocity,
		const DtVector &	newBodyAcceleration,
		double	dT
	)		`[protected, virtual]`

virtual DtVector DtRailMovementUpdater::calculateProjectedLocation	(	const DtVector &	oldLocalPosition,
		const DtVector &	newBodyAcceleration,
		const DtVector &	oldBodyVelocity,
		const DtVector &	newBodyVelocity,
		double	newHeading
	)		`[protected, virtual]`

virtual bool DtRailMovementUpdater::rotationalVelocityShouldBeClamped ( const DtVector & bodyRotationalVelocity ) [protected, virtual]

Returns true if given magnitude of body rotational velocity is < 0.0001 radians/sec, false otherwise.

Called in tick() to determine whether or not to clamp small values for velocity to zero.

virtual bool DtRailMovementUpdater::passedTurnPoint	(	double	distSq,
		double &	differance
	)		`[protected, virtual]`

Determines if the entity has gone passed the point at which it should start to turn.

If not using turn smoothing this is simply the end point of the current segment the entity is on.

virtual DtVector DtRailMovementUpdater::determinePositionAlongNextSegment	(	DtRailSegment *	nextSegment,
		double	distance,
		double &	newHeading,
		int	lanePos,
		DtVector	projectedPos
	)		`[protected, virtual]`

When the entity moves past the end point of it's current segment, the remaining distance traveled is then applied along the next segment to determine where the entity is on the segment.

The heading of the new segment is returned since this will then be the heading of the the entity. This is used when the entity is not using turn smoothing or the distance traveled takes the entity beyond the turn in this tick.

Parameters:

distance	is the distance beyond the current segment that the vehicle has traveled.
projectedPos	is the current local position updated for this tick with a dT's worth of velocity and acceleration.

Returns:: An updated local position. If the next segment has a slightly different direction, the vehicle position may be shifted slightly.

virtual void DtRailMovementUpdater::determinePosition	(	const DtRailSegment *	currentSeg,
		const double	distSq,
		const int	currentLane,
		DtVector &	newLocalProjectedLocation
	)		`[protected, virtual]`

Get position relative to lane along segment.

const DtRailMovementUpdater& DtRailMovementUpdater::operator= ( const DtRailMovementUpdater & orig ) [private]

assignment operator; not implemented

Member Data Documentation

DtRailMovementController* DtRailMovementUpdater::myController [protected]

DtVrfMovingObjectStateRepository* DtRailMovementUpdater::myMovingStateRep [protected]

const DtAttachedTerrain* DtRailMovementUpdater::myAttachedTerrain [protected]

Used to ground clamp the entity-- TODO how we ground clamp, ie get access to terrain may change, we might want to instead just point to the physical world.

DtCoordTransform DtRailMovementUpdater::myCoordTransform [protected]

bool DtRailMovementUpdater::myUseHighFidelityGroundClamping [protected]

Only calculate these when switching rails, expensive.

bool DtRailMovementUpdater::myUseAcceleration [protected]

bool DtRailMovementUpdater::myUseTurnSmoothing [protected]

double DtRailMovementUpdater::myDistanceSqToTurn [protected]

This is the distance from the current segment's startpoint to the turn point on the segment.

double DtRailMovementUpdater::myHeadingDiff [protected]

Difference between our current segment's heading and our next segment.

Used for turn smoothing.

DtRailSplineCalculator DtRailMovementUpdater::myTurnSpline [protected]

Handles turning from one rail to another using a quadratic spline curve.