Functions
DT_DLL_vrfutil double	distance2DSqAlongRailSegment (const DtVector &pos, const DtRailSegment *seg, const Coordinate_System &coordinateSystem, double &distanceToSeg)
	Set of Useful functions when an entity is moving along rails.
DT_DLL_vrfutil double	distance2DAlongRailFromStart (const DtVector &pos, const DtRailSegmentList *rails, const Coordinate_System &coordinateSystem)
	How far from the start of the rail path pos is. This is distance along the path not as the crow flies.
DT_DLL_vrfutil DtVector	locationAlongRail (double distanceFromStart, const DtRailSegmentList *rails, const Coordinate_System &coordinateSystem)
DT_DLL_vrfutil DtVector	locationAlongRailSegment (double distanceFromSegmentStart, const DtRailSegment *railSegment)
DT_DLL_vrfutil double	railHeading (const DtRailSegment *railSegment, const Coordinate_System &coordinateSystem)
	Returns the heading from the start point to the end point of the given rail segment in the given coordinate system.
DT_DLL_vrfutil int	findTurnDirection (double currentHeading, double desiredHeading, double &headingDiff)
	Returns which direction the turn is, -1 indicates left, 1 indicates right.
DT_DLL_vrfutil bool	intersection (const DtRailSegment currentSegment, const DtRailSegment nextSegment)
	Given two segments, determine if where they meet is an intersection or just a bend in the road.
DT_DLL_vrfutil int	findDrivingLane (const int turnDirection, const DtRailSegment *segment)
	Given the direction we want to turn determine the driving lane to be in.
DT_DLL_vrfutil const DtRailSegment *	findClosestSegment (const DtVector &pos, const DtRailSegmentList *rails, const Coordinate_System &coordinateSystem, double &distanceSqAlongClosest)
DT_DLL_vrfutil double	distance2DAlongRailBetween2Points (const DtVector &pos1, const DtVector &pos2, const DtRailSegmentList *rails, const Coordinate_System &coordinateSystem)
	Distance between two positions on the rail path.
DT_DLL_vrfutil double	closestPointInXY (const DtRailSegment *seg, const DtVector &pointFronm, DtVector &closest, const Coordinate_System &coordinateSystem)
DT_DLL_vrfutil double	laneLengthTurnAdjustment (const DtRailSegment *seg, const int lane, const double headingChange)
	This function calculates the difference in lane length from the segment centerline length because it is outside or inside of the turn (to the following segment) relative to the rail segment center line.
DT_DLL_vrfutil DtRailSegment *	generateEntryPoint (const DtPoint &entry, DtRailSegmentList *rails, const DtVector &entityPos, bool drivingOnLeft, bool pivots, const double turnRadius, const double entityHeading, DtVector &entryPoint, const Coordinate_System &coordinateSystem)
	Generates an entry rail segment to get the entity smoothly onto the rail path.
DT_DLL_vrfutil void	setUpLocalToBodyCoordinateTransform (const DtVector &offset, const double heading, const Coordinate_System &coordinateSystem, DtCoordTransform &transform)
	Returns a coordinate transform matrix to transform from local coordinates to the body coordinates based on the heading of the passed in rail segment and using the segment's end point as the offset.
DT_DLL_vrfutil DtRwRailSegmentList *	createRwRailPath (const DtRailSegmentList *rails)
DT_DLL_vrfutil DtRwRailSegmentList *	createRwRailPathFromRoute (DtLocalVectorIterator &routeIter, const DtVector startPos, DtIteratorDirection dir, bool startAtClosestPt, const Coordinate_System &coordinateSystem)
DT_DLL_vrfutil void	fillInRailPathFromRoute (DtLocalVectorIterator &routeIter, const DtVector startPos, DtIteratorDirection dir, bool startAtClosestPt, const Coordinate_System &coordinateSystem, DtRailSegmentList &rails)
DT_DLL_vrfutil bool	calcOrthoOffset (const DtPoint &startPoint, const DtPoint &endPoint, double distance, DtPoint &leftOffset, DtPoint &rightOffset)
	This function generates two offset values that can be used for any point on the given segment.
DT_DLL_vrfutil bool	findPointOnLine (const DtPoint &startPoint, const DtPoint &endPoint, DtPoint &result, double distance)
	The end point is mostly only for directionality of the resulting point.
DT_DLL_vrfutil bool	isRailWithinDistance (const Coordinate_System coordSys, const DtVector &sourceLocation, DtRailSegment railSegment, double allowDistance, double &actualDistSq)
DT_DLL_vrfutil bool	isLocationWithinRoad (const Coordinate_System coordSys, const DtVector &sourceLocation, DtRailSegment railSegment)
DT_DLL_vrfutil DtVector	convertGeocVecToTopo (const DtVector &geocPoint, const DtCoordTransform &matrix)
	This function converts a point (not a vector) using the given transformation matrix–which is expected to be a geoc to topo transformation.
DT_DLL_vrfutil DtVector	convertTopoVecToGeoc (const DtVector &topoPoint, const DtCoordTransform &matrix)
	Similarly.
DT_DLL_vrfutil DtCoordTransform	generateTransformMatrix (const DtVector &geocViewpoint)
DT_DLL_vrfutil bool	removeShortSegmentsFromRailPath (DtRailSegmentList &railPath, const double allowedError, const Coordinate_System *localCoordinateSystem, bool debug=false)
	This function removes short segments from a rail path when possible so that feasible vehicle paths can more easily be found to traverse it.

Detailed Description

Function Documentation

DT_DLL_vrfutil double distance2DSqAlongRailSegment	(	const DtVector &	pos,
		const DtRailSegment *	seg,
		const Coordinate_System &	coordinateSystem,
		double &	distanceToSeg
	)

Set of Useful functions when an entity is moving along rails.

Returns distance along provided rail segment pos is. distanceToSeg is the perpendicular distance from the segment the point is, ie to closest point on the segment

DT_DLL_vrfutil double distance2DAlongRailFromStart	(	const DtVector &	pos,
		const DtRailSegmentList *	rails,
		const Coordinate_System &	coordinateSystem
	)

How far from the start of the rail path pos is. This is distance along the path not as the crow flies.

DT_DLL_vrfutil DtVector locationAlongRail	(	double	distanceFromStart,
		const DtRailSegmentList *	rails,
		const Coordinate_System &	coordinateSystem
	)

Returns: The local position which is the specified distance along the rail from the start.

DT_DLL_vrfutil DtVector locationAlongRailSegment	(	double	distanceFromSegmentStart,
		const DtRailSegment *	railSegment
	)

Returns: The local position which is the specified distance from the start of the rail segment.

DT_DLL_vrfutil double railHeading	(	const DtRailSegment *	railSegment,
		const Coordinate_System &	coordinateSystem
	)

Returns the heading from the start point to the end point of the given rail segment in the given coordinate system.

DT_DLL_vrfutil int findTurnDirection	(	double	currentHeading,
		double	desiredHeading,
		double &	headingDiff
	)

Returns which direction the turn is, -1 indicates left, 1 indicates right.

The difference in the 2 headings is returned in headingDiff.

DT_DLL_vrfutil bool intersection	(	const DtRailSegment *	currentSegment,
		const DtRailSegment *	nextSegment
	)

Given two segments, determine if where they meet is an intersection or just a bend in the road.

DT_DLL_vrfutil int findDrivingLane	(	const int	turnDirection,
		const DtRailSegment *	segment
	)

Given the direction we want to turn determine the driving lane to be in.

DT_DLL_vrfutil const DtRailSegment* findClosestSegment	(	const DtVector &	pos,
		const DtRailSegmentList *	rails,
		const Coordinate_System &	coordinateSystem,
		double &	distanceSqAlongClosest
	)

DT_DLL_vrfutil double distance2DAlongRailBetween2Points	(	const DtVector &	pos1,
		const DtVector &	pos2,
		const DtRailSegmentList *	rails,
		const Coordinate_System &	coordinateSystem
	)

Distance between two positions on the rail path.

DT_DLL_vrfutil double closestPointInXY	(	const DtRailSegment *	seg,
		const DtVector &	pointFronm,
		DtVector &	closest,
		const Coordinate_System &	coordinateSystem
	)

DT_DLL_vrfutil double laneLengthTurnAdjustment	(	const DtRailSegment *	seg,
		const int	lane,
		const double	headingChange
	)

This function calculates the difference in lane length from the segment centerline length because it is outside or inside of the turn (to the following segment) relative to the rail segment center line.

E.g. outside is a lane to the right of center when the next segment turns left. The sign of the lane does not matter; it is only used to determine the distance of the lane center from the segment center line. The heading change should be positive, regardless of turn direction. Heading change is in radians.

DT_DLL_vrfutil DtRailSegment* generateEntryPoint	(	const DtPoint &	entry,
		DtRailSegmentList *	rails,
		const DtVector &	entityPos,
		bool	drivingOnLeft,
		bool	pivots,
		const double	turnRadius,
		const double	entityHeading,
		DtVector &	entryPoint,
		const Coordinate_System &	coordinateSystem
	)

Generates an entry rail segment to get the entity smoothly onto the rail path.

Provides the entry point in database coordinates. If the entity is already on the road, just move up the entry segment to allow the entity to drive to the start of the segment, no need for an entry segment. Returns the DtVector entryPoint which is the new point the entity should head towards to get onto the rail. If a entry rail segment is created it will be returned and the entryPoint will be it's starting point.

DT_DLL_vrfutil void setUpLocalToBodyCoordinateTransform	(	const DtVector &	offset,
		const double	heading,
		const Coordinate_System &	coordinateSystem,
		DtCoordTransform &	transform
	)

Returns a coordinate transform matrix to transform from local coordinates to the body coordinates based on the heading of the passed in rail segment and using the segment's end point as the offset.

DT_DLL_vrfutil DtRwRailSegmentList* createRwRailPath ( const DtRailSegmentList * rails )

DT_DLL_vrfutil DtRwRailSegmentList* createRwRailPathFromRoute	(	DtLocalVectorIterator &	routeIter,
		const DtVector	startPos,
		DtIteratorDirection	dir,
		bool	startAtClosestPt,
		const Coordinate_System &	coordinateSystem
	)

DT_DLL_vrfutil void fillInRailPathFromRoute	(	DtLocalVectorIterator &	routeIter,
		const DtVector	startPos,
		DtIteratorDirection	dir,
		bool	startAtClosestPt,
		const Coordinate_System &	coordinateSystem,
		DtRailSegmentList &	rails
	)

DT_DLL_vrfutil bool calcOrthoOffset	(	const DtPoint &	startPoint,
		const DtPoint &	endPoint,
		double	distance,
		DtPoint &	leftOffset,
		DtPoint &	rightOffset
	)

This function generates two offset values that can be used for any point on the given segment.

The offset values generated will be oriented depending on which value is used as the start point and will always be in that direction (regardless of true orientation). The endpoint of the segment is a reference point for the calculations and determines the orientation of the offsets. The distance to the endpoint only needs to be non-zero. Returns true if it calculated the offset values, otherwise will return false;

     leftOffset
         * 
         | distance
         |

startPoint *-----------—* endPoint | | distance

rightOffset

DT_DLL_vrfutil bool findPointOnLine	(	const DtPoint &	startPoint,
		const DtPoint &	endPoint,
		DtPoint &	result,
		double	distance
	)

The end point is mostly only for directionality of the resulting point.

The left parenthesis below is the location of the resulting point. Despite the name and usage of the function, it's mostly used to calculate a point on a segment that is distance D from one endpoint. If the segment itself either doesn't exist, or the endpoint is within the distance, this should still work as long as the distance between the two points is not 0. If it is, it will simply return the startPoint.

    D            endPoint
  *----)---------*

startPoint

DT_DLL_vrfutil bool isRailWithinDistance	(	const Coordinate_System *	coordSys,
		const DtVector &	sourceLocation,
		DtRailSegment *	railSegment,
		double	allowDistance,
		double &	actualDistSq
	)

DT_DLL_vrfutil bool isLocationWithinRoad	(	const Coordinate_System *	coordSys,
		const DtVector &	sourceLocation,
		DtRailSegment *	railSegment
	)

DT_DLL_vrfutil DtVector convertGeocVecToTopo	(	const DtVector &	geocPoint,
		const DtCoordTransform &	matrix
	)

This function converts a point (not a vector) using the given transformation matrix–which is expected to be a geoc to topo transformation.

DT_DLL_vrfutil DtVector convertTopoVecToGeoc	(	const DtVector &	topoPoint,
		const DtCoordTransform &	matrix
	)

Similarly.

DT_DLL_vrfutil DtCoordTransform generateTransformMatrix ( const DtVector & geocViewpoint )

DT_DLL_vrfutil bool removeShortSegmentsFromRailPath	(	DtRailSegmentList &	railPath,
		const double	allowedError,
		const Coordinate_System *	localCoordinateSystem,
		bool	debug = `false`
	)

This function removes short segments from a rail path when possible so that feasible vehicle paths can more easily be found to traverse it.

"When possible" means that the segments have to be in a straight line (no eliminated segment start point can be farther than allowedError from the resulting line from start to end of the straightened segment), and segment properties have to be constant over the straightened region: is-one-way, number of lanes, lane width, and segment speed.

Parameters

railPath	is the rail path to process; it is modified.
allowedError	is the maximum distance an eliminated start/end rail segment point can be from the line from start to end of the straightened segment.
localCoordinateSystem	is the terrain coordinate system. The error test for removal is based on horizontal, 2D distance.

Returns: true if any short segments were removed, false otherwise.

Functions

Detailed Description

Function Documentation