A Location specifies a position on a track system by referencing a track and a TrackLocation on it. More...

#include <C:/Trend/Development/Trax3/Code/trax/Location.h>

Public Member Functions

dclspc void PutOn (std::shared_ptr< const Track > pTrack, const TrackLocation &tl)

Attaches this Location onto the specified track.

dclspc void PutOff () noexcept

Removes the Location from its position on the track.

dclspc bool IsOnTrack () const noexcept

dclspc std::shared_ptr< const Track > GetTrack () const noexcept

Gets the track this Location is on.

dclspc Length Param () const noexcept

dclspc Orientation Orient () const noexcept

dclspc AnglePerLength Curvature () const

dclspc AnglePerLength Torsion () const

dclspc void TNBFrame (spat::Frame< Length, One > &frame) const

Receives the TNB - Frame of the curve at the location.

dclspc void Get (TrackLocation &tl) const noexcept

Gets the TrackLocation - data of this track location.

dclspc void Get (TrackLocationRef &tlr) const noexcept

Gets the TrackLocationRef - data of this track location.

dclspc std::shared_ptr< Track > GetMutableTrack () const noexcept

Gets mutable track access.

dclspc Location () noexcept=default

Construction.

dclspc Location (const Location &location) noexcept=default

Construction.

dclspc Location (Location &&location) noexcept=default

Construction.

dclspc Location (std::shared_ptr< const Track > pTrack, const TrackLocation &tl)

Construction.

dclspc Location (const Track &track, const TrackLocation &tl)

Construction.

dclspc Location & operator= (const Location &location) noexcept=default

Assignment.

dclspc Location & operator= (Location &&location) noexcept=default

Assignment.

Transition

Copys the 3D position and orientation of this Location.

Coordinates are calculated in the global frame.

Parameters

pos	Reference to a Position to receive the 3d location.
tan	Reference to a Vector to receive the 3D tangential vector.
bundle	Reference to a VectorBundle to receive the full 3D position and tangential vector.
frame	Reference to a Frame to receive the full 3d location and orientation.
td	Reference to a track data struct. Receives the data in engine units. Used by trackjoints and trackfeeders internally.

Exceptions

std::logic_error	if the location is not on track.
std::exception	if the transition could not get performed.

dclspc void Transition (spat::Position< Length > &pos) const

dclspc void Transition (spat::Vector< One > &tan) const

dclspc void Transition (spat::VectorBundle< Length, One > &bundle) const

dclspc void Transition (spat::VectorBundle2< Length, One > &bundle) const

dclspc void Transition (spat::Frame< Length, One > &frame) const

dclspc void Transition (TrackData< Real > &td, Real engine_meters_per_unit) const

Move

Moves this Location by dParam along the tracks with respect to actual switch settings.

Optionally the function receives signals and triggers sensors. If a dead end of a track (uncoupled track end) is reached that end's position will be the resulting location. All sensors in the valid range get triggered for the given Event and all signals be dispatched to the SignalTarget.

Parameters

dParam	Incremental value to move the location in the direction of the track (not the locations positive orientation). Be aware that huge values in combination with cyclic track systems might result in long execution times of this function.
principalDirection	Specifies the direction of movement relative to the Location's orientation. This is used to receive signals and might differ from the sign of ds. For one, ds might be zero, for second it might happen that an actual movement is oriented against the principal direction.
pEvent	Trigger sensors and dispatch Event.
pSignalTarget	Receive signals.

Returns: 0m if the movement could get accomplished. If a dead end was encountered during movement the leftover parameter value is returned. I.e.: if the dead end would be connected a new move operation with that very value would lead to the correct position. The bool flag indicates wether one or more track transitions have been performed during the operation.

Exceptions

std::exception if the move could not get performed.

dclspc std::pair< Length, bool > Move (Length dParam)

dclspc std::pair< Length, bool > Move (Length dParam, const Event *pEvent)

dclspc std::pair< Length, bool > Move (Length dParam, Orientation principalDirection, SignalTarget *pSignalTarget)

dclspc std::pair< Length, bool > Move (Length dParam, Orientation principalDirection, const Event *pEvent, SignalTarget *pSignalTarget)

MoveToEnd

Moves this Location to the specified end of the track without transitioning to the next.

Parameters

direction	para moves to the tracks end in Track's direction, anti against it.
pEvent	Trigger sensors and dispatch Event.
pSignalTarget	Receive signals.

Returns: The parameter length the location moved.

Exceptions

std::exception if the move could not get performed.

dclspc Length MoveToEnd (Orientation direction=Orientation::Value::para, const Event *pEvent=nullptr, SignalTarget *pSignalTarget=nullptr)

Moves the location to the track's end and transitions it to the coupled track's end if any.

dclspc std::pair< Length, bool > MoveTransit (Orientation direction=Orientation::Value::para, const Event *pEvent=nullptr, SignalTarget *pSignalTarget=nullptr)

Moves the location to the track's end and transitions it to the coupled track's end if any.

dclspc Location & Flip () noexcept

Turns the direction of this location to the other side.

dclspc bool Equals (const Location &loc, Length epsilon) const noexcept

Compares two Locations.

dclspc Length Distance (const Location &loc, Length maxdistance) const

Gets the parameter distance between two locations.

Reservation mechanism

See also: Track

dclspc void Reserve (common::Interval< Length > range, IDType forID)

Reserves a range on the track relative to this Location.

dclspc void DeleteReservation (IDType forID=anyID)

Deletes a reservation.

dclspc std::vector< Track::Overlap > Overlaps (IDType forID) const

Finds overlapping areas for reservations.

Detailed Description

A Location specifies a position on a track system by referencing a track and a TrackLocation on it.

It provides member functions for moving along a track, triggering Sensors and receiving Signals that are attached along the tracks. Use it to get information such as 3D position about a location on a track system.

Constructor & Destructor Documentation

◆ Location() [1/5]

dclspc trax::Location::Location ( )

defaultnoexcept

Construction.

The non-default constructor will resolve the location (calculating the correct track if tl is outside pTrack's range).

Exceptions

std::out_of_range if the track system location could not get resolved.

◆ Location() [2/5]

dclspc trax::Location::Location ( const Location & location )

defaultnoexcept

Construction.

The non-default constructor will resolve the location (calculating the correct track if tl is outside pTrack's range).

Exceptions

std::out_of_range if the track system location could not get resolved.

◆ Location() [3/5]

dclspc trax::Location::Location ( Location && location )

defaultnoexcept

Construction.

The non-default constructor will resolve the location (calculating the correct track if tl is outside pTrack's range).

Exceptions

std::out_of_range if the track system location could not get resolved.

◆ Location() [4/5]

dclspc trax::Location::Location	(	std::shared_ptr< const Track >	pTrack,
		const TrackLocation &	tl )

Construction.

The non-default constructor will resolve the location (calculating the correct track if tl is outside pTrack's range).

Exceptions

std::out_of_range if the track system location could not get resolved.

◆ Location() [5/5]

dclspc trax::Location::Location	(	const Track &	track,
		const TrackLocation &	tl )

Construction.

The non-default constructor will resolve the location (calculating the correct track if tl is outside pTrack's range).

Exceptions

std::out_of_range if the track system location could not get resolved.

Member Function Documentation

◆ Curvature()

dclspc AnglePerLength trax::Location::Curvature ( ) const

Returns: the curvature of the curve at the location.

Exceptions

std::exception if the curvature was not available.

◆ DeleteReservation()

dclspc void trax::Location::DeleteReservation ( IDType forID = anyID )

Deletes a reservation.

Exceptions

std::logic_error if the location is not on track.

◆ Distance()

dclspc Length trax::Location::Distance	(	const Location &	loc,
		Length	maxdistance ) const

Gets the parameter distance between two locations.

Parameters

loc	Location to search for behind this location if maxdistance < 0 or in front of it if maxdistance > 0.
maxdistance	If the distance outgrews maxdistance, maxdistance is returned.

Exceptions

std::logic_error	exception if one of the locations is not attached to a track.
std::out_of_range	exception if it hits a not connected track end before finding loc.

Returns: The distance along the curve between this location and loc or maxdistance if loc was not found.

Exceptions

std::logic_error	if any of the locations is not at a valid position.
std::out_of_range	if the search ended at an open track end.

◆ Equals()

dclspc bool trax::Location::Equals	(	const Location &	loc,
		Length	epsilon ) const

noexcept

Compares two Locations.

The comparison will work with Locations on coupled tracks.

Returns: true if the two Locations stand for the same locations along the track system with a difference smaller than epsilon in parameter difference; false otherwise.

◆ GetMutableTrack()

dclspc std::shared_ptr< Track > trax::Location::GetMutableTrack ( ) const

noexcept

Gets mutable track access.

Returns: Non-const track pointer or nullptr if unavailable.

◆ GetTrack()

dclspc std::shared_ptr< const Track > trax::Location::GetTrack ( ) const

noexcept

Gets the track this Location is on.

Returns: The track or nullptr if no track is assigned.

◆ IsOnTrack()

dclspc bool trax::Location::IsOnTrack ( ) const

noexcept

Returns: True if the Location is put on a rail; false otherwise.

◆ MoveToEnd()

dclspc Length trax::Location::MoveToEnd	(	Orientation	direction = Orientation::Value::para,
		const Event *	pEvent = nullptr,
		SignalTarget *	pSignalTarget = nullptr )

Moves the location to the track's end and transitions it to the coupled track's end if any.

Parameters

direction	para moves to the tracks end in Track's direction, anti against it.
pEvent	Trigger sensors and dispatch Event.
pSignalTarget	Receive signals.

Returns: the distance that the Location was moved and a flag that indicates wether a track transition actually happened.

Exceptions

std::exception if the move could not get performed.

◆ MoveTransit()

dclspc std::pair< Length, bool > trax::Location::MoveTransit	(	Orientation	direction = Orientation::Value::para,
		const Event *	pEvent = nullptr,
		SignalTarget *	pSignalTarget = nullptr )

Moves the location to the track's end and transitions it to the coupled track's end if any.

Parameters

direction	para moves to the tracks end in Track's direction, anti against it.
pEvent	Trigger sensors and dispatch Event.
pSignalTarget	Receive signals.

Returns: the distance that the Location was moved and a flag that indicates wether a track transition actually happened.

Exceptions

std::exception if the move could not get performed.

◆ Orient()

dclspc Orientation trax::Location::Orient ( ) const

noexcept

Returns: the orientation of the location.

◆ Overlaps()

dclspc std::vector< Track::Overlap > trax::Location::Overlaps ( IDType forID ) const

Finds overlapping areas for reservations.

Exceptions

std::logic_error	if the location is not on track.
std::exception	if the overlaps could not get collected.

◆ Param()

dclspc Length trax::Location::Param ( ) const

noexcept

Returns: the arc length of the location.

◆ PutOn()

dclspc void trax::Location::PutOn	(	std::shared_ptr< const Track >	pTrack,
		const TrackLocation &	tl )

Attaches this Location onto the specified track.

The track location gets resolved; this means that if the parameter value is out of Track::Range() for this track, the method tries to find the track for the position on coupled tracks. If a dead end is encountered in this process a std::out_of_range exception gets thrown.

Parameters

pTrack	The track relativ to wich tl is formulated.
tl	Parameter value and orientation on the track.

Exceptions

std::invalid_argument	if pTrack is nullptr or the track is invalid.
std::out_of_range	if the location could not get resolved.

◆ Reserve()

dclspc void trax::Location::Reserve	(	common::Interval< Length >	range,
		IDType	forID )

Reserves a range on the track relative to this Location.

Exceptions

std::logic_error	if the location is not on track.
std::range_error	If the range lays completely outside the track.

◆ TNBFrame()

dclspc void trax::Location::TNBFrame ( spat::Frame< Length, One > & frame ) const

Receives the TNB - Frame of the curve at the location.

The Frame received by the Transition() methods is aligned to Locations orientation on the tracks and a twisting of the line. For dynamic calculations the real geometry of the curve is needed.

◆ Torsion()

dclspc AnglePerLength trax::Location::Torsion ( ) const

Returns: the torsion of the curve at the location.

Exceptions

std::exception if the torsion was not available.

The documentation for this class was generated from the following file:

C:/Trend/Development/Trax3/Code/trax/Location.h