Track.h

Go to the documentation of this file.

//  trax track library
//  AD 2013 
//
//  "I will love you 'till the end of time"
//
//                              Lana Del Rey
//
// Copyright (c) 2025 Trend Redaktions- und Verlagsgesellschaft mbH
// Copyright (c) 2019 Marc-Michael Horstmann
//
// Permission is hereby granted to any person obtaining a copy of this software 
// and associated source code (the "Software"), to use, view, and study the 
// Software for personal or internal business purposes, subject to the following 
// conditions:
//
// 1. Redistribution, modification, sublicensing, or commercial use of the 
// Software is NOT permitted without prior written consent from the copyright 
// holder.
//
// 2. The Software is provided "AS IS", without warranty of any kind, express 
// or implied.
//
// 3. All copies of the Software must retain this license notice.
//
// For further information, please contact: horstmann.marc@trendverlag.de
 
#pragma once

 
#include "IDType.h"
#include "Units.h"
#include "Identified.h"
#include "Orientation.h"
#include "RoadwayTwist.h"
 
#include "common/Interval.h"
#include "spat/Box.h"
#include "spat/Frame.h"
#include "spat/Vector2D.h"
#include "spat/VectorBundle.h"
#include "spat/VectorBundle2.h"
 
namespace trax
{
    struct Body;
    struct Connector;
    struct Curve;
    struct Event;
    struct MovableTrack;
    struct ParallelizableTrack;
    struct RoadwayTwist;
    struct Sensor;
    struct Signal;
    struct SignalTarget;
    template<typename> struct TrackData;
    struct TrackBuilder;
    struct TrackLocation;
    struct TrackRange;

    struct TrackUserData;
 

    struct Track : Identified<Track>
    {
        virtual const char* TypeName() const noexcept = 0;
 
        enum class TrackType : char{
            unknown = -1,
            none  = 0,
            standard,
            withGeoms,
            movable,
            movable_autoconnecting,
            parallel
        };
 
        virtual TrackType GetTrackType() const noexcept = 0;

        enum class EndType : char{
            none    = -1,
            front   = 0,    
            end     = 1,    
            any             
        };
 
        typedef std::pair<std::shared_ptr<Track>,EndType> TrackEnd;
        typedef std::pair<std::shared_ptr<const Track>,const EndType> cTrackEnd;

        struct End{
            End() noexcept = default;
            End( IDType id, EndType type ) noexcept
            : id    { id },
              type  { type }
            {}
 
            End( const TrackEnd& trackEnd ) noexcept
            : id    { trackEnd.first ? trackEnd.first->ID() : IDType{0u} },
              type  { trackEnd.second }
            {}
 
            End( const std::pair<std::shared_ptr<TrackBuilder>,Track::EndType>& trackEnd ) noexcept;
 
            IDType  id;                     
            EndType type = EndType::none;   
        };
 

        struct Coupling{
            End theOne;     
            End theOther;   
        };
 

    
        virtual std::shared_ptr<const TrackBuilder> This() const noexcept = 0;

        virtual std::shared_ptr<TrackBuilder> This() noexcept = 0;
 

        
        virtual std::shared_ptr<const MovableTrack> GetMovableTrack() const noexcept = 0;
 
        virtual std::shared_ptr<MovableTrack> GetMovableTrack() noexcept = 0;

        
        virtual std::shared_ptr<const ParallelizableTrack> GetParallelizableTrack() const noexcept = 0;
 
        virtual std::shared_ptr<ParallelizableTrack> GetParallelizableTrack() noexcept = 0;
 

        virtual std::shared_ptr<const Body> GetBody() const noexcept = 0;
 

        virtual bool IsValid() const noexcept = 0;
 

        virtual Length GetLength() const noexcept = 0;
 

        virtual common::Interval<Length> Range() const noexcept = 0;
 

        virtual bool IsCoupled( EndType atend = EndType::any ) const noexcept = 0;
 

        virtual AnglePerLength Curvature( Length s ) const = 0;
 

        virtual AnglePerLength Torsion( Length s ) const = 0;
 

        virtual Angle GetTwistValue( Length s ) const = 0;
 

        virtual AnglePerLength GetTwistD1( Length s ) const = 0;
 

        virtual bool IsFlat() const noexcept = 0;
 

        virtual spat::Vector<One> LocalUp() const = 0;
 

        virtual void TNBFrame( Length s, spat::Frame<Length,One>& frame ) const = 0;
 


        virtual void Transition( Length s, spat::Position<Length>& pos ) const = 0;
 
        virtual void Transition( Length s, spat::Vector<One>& tan ) const = 0;
 
        virtual void Transition( Length s, spat::VectorBundle<Length,One>& bundle ) const = 0;
 
        virtual void Transition( Length s, spat::VectorBundle2<Length,One>& bundle ) const = 0;
 
        virtual void Transition( Length s, spat::Frame<Length,One>& frame ) const = 0;
 
        virtual void Transition( Length s, TrackData<Real>& td, Real engine_meters_per_unit ) const = 0;
 

        virtual TrackEnd TransitionEnd( EndType thisEnd ) const noexcept = 0;
 

        virtual void DoTrigger( const common::Interval<Length>& range, const Event& _event ) const = 0;
 

        virtual bool DoSignal( const common::Interval<Length>& range, Orientation orientation, SignalTarget& signalTarget ) const = 0;
 

        virtual Signal* GetSignal( const TrackLocation& loc ) const noexcept = 0;
 

        virtual Connector* GetConnector( EndType atend ) const noexcept = 0;
 

        virtual Connector* GetConnector( const Orientation& inDirection ) const noexcept = 0;
 


        virtual void Reserve( common::Interval<Length> range, IDType forID ) = 0;
 
        using Reservation = std::tuple<IDType,common::Interval<Length>>;
        using ReservationIterator = std::vector<Reservation>::const_iterator;

        virtual ReservationIterator BeginReservations() const noexcept = 0;

        virtual ReservationIterator EndReservations() const noexcept = 0;

        virtual void DeleteReservation( common::Interval<Length> inRange, IDType forID = anyID ) noexcept = 0;
 

        virtual bool IsReserved( common::Interval<Length> inRange, IDType forID = anyID ) const noexcept = 0;
 

        struct Overlap{
            IDType forID;   
            bool forNear;   
            bool forFar;    
            IDType withID;  
            bool withNear;  
            bool withFar;   
        };
 

        virtual std::vector<Overlap> Overlaps( IDType forID ) const = 0;
 

        virtual void UserData( TrackUserData* pData ) noexcept = 0;
 

        virtual TrackUserData* UserData() const noexcept = 0;
    };

    dclspc const char* ToString( Track::TrackType type );

    dclspc Track::TrackType TrackType( const std::string& type ) noexcept;

    inline bool operator==( const Track::End& theone, const Track::End& theother ) noexcept;
 

    inline bool operator!=( const Track::End& theone, const Track::End& theother ) noexcept;
 

    inline bool operator==( const Track::Coupling& theone, const Track::Coupling& theother ) noexcept;
 

    inline bool operator!=( const Track::Coupling& theone, const Track::Coupling& theother ) noexcept;
 
 
    inline bool operator==( const Track::Overlap& a, const Track::Overlap& b ) noexcept;
 
    inline bool operator<( const Track::Overlap& a, const Track::Overlap& b ) noexcept;
 

    dclspc std::string ToString( Track::EndType end );
 

    dclspc Track::EndType ToEndType( const std::string& end );
 

    inline Track::EndType operator!( Track::EndType end ) noexcept{
        return end == Track::EndType::front ? Track::EndType::end : Track::EndType::front;
    }
 


    dclspc Length Segment( const Track& track, Length s, Length e, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    dclspc Length Segment( const Track& track, Length s, Length e, Length w, Length h, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    dclspc Length Segment_Checked( const Track& track, Length s, Length e, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    dclspc Length Segment_Checked( const Track& track, Length s, Length e, Length w, Length h, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    dclspc Length Segment_TotallyChecked( const Track& track, Length s, Length e, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    dclspc Length Segment_TotallyChecked( const Track& track, Length s, Length e, Length w, Length h, common::Interval<Length> segmentLimits, bool ignoreCuvesTorsion = false );
 

    
    dclspc std::pair<bool,Length> Foot( const spat::Position<Length>& ofPoint, const Track& toTrack );
 
    dclspc std::pair<bool,Length> Foot( const spat::Position<Length>& ofPoint, const Track& toTrack, Length bestGuess );
 
    dclspc std::pair<bool,Length> Foot( const spat::Position<Length>& ofPoint, const Track& toTrack, Length bestGuess, common::Interval<Length> inRange );

    dclspc std::pair<bool,Length> Foot( const spat::VectorBundle<Length,One>& ofRay, const Track& toTrack );
 
    dclspc std::pair<bool,Length> Foot( const spat::VectorBundle<Length,One>& ofRay, const Track& toTrack, Length bestGuess );
 
    dclspc std::pair<bool,Length> Foot( const spat::VectorBundle<Length,One>& ofRay, const Track& toTrack, Length bestGuess, common::Interval<Length> inRange );
 

    
    dclspc Length Closest( const spat::Position<Length>& toPoint, const Track& onTrack, bool includeEndpoints = true );

    dclspc Length Closest( const spat::VectorBundle<Length,One>& toRay, const Track& onTrack, bool includeEndpoints = true );
 

    dclspc void Couple( std::pair<std::shared_ptr<Track>,Track::EndType> trackA, std::pair<std::shared_ptr<Track>,Track::EndType> trackB );
 

    dclspc Length DistanceOf( Track::cTrackEnd trackEndA, Track::cTrackEnd trackEndB );
 

    dclspc Length DistanceToCoupled( const Track& track, Track::EndType atEnd );
 

    dclspc Angle KinkToCoupled( const Track& track, Track::EndType atEnd );
 

    dclspc Angle TwistToCoupled( const Track& track, Track::EndType atEnd );
 
 

    struct TrackBuilder : Track
    {
        static dclspc std::shared_ptr<TrackBuilder> Make( TrackType type = TrackType::standard ) noexcept;
 

        
        virtual void SetFrame( const spat::Frame<Length,One>& frame ) noexcept = 0;
 

        virtual void SetFrame( const spat::Frame<Length,One>& start, Length s, bool bAllowTwistOffset = true ) = 0;
 

        virtual const spat::Frame<Length,One>& GetFrame() const noexcept = 0;
 

        virtual const spat::Frame<Length,One>& GetAbsoluteFrame() const noexcept = 0;
 

        virtual void Couple( std::pair<std::shared_ptr<TrackBuilder>,Track::EndType> thisEnd, std::pair<std::shared_ptr<TrackBuilder>,Track::EndType> othersEnd ) = 0;
 

        virtual void DeCouple( EndType thisEnd = EndType::any, bool oneSided = false ) = 0;
 

        
        virtual void Attach( std::shared_ptr<const Curve> pCurve, common::Interval<Length> curveSegment = {0_m,+infinite__length} ) = 0;
 
        virtual void Attach( std::pair<std::shared_ptr<const Curve>,common::Interval<Length>> curve ) = 0;
 
        virtual void Attach( std::pair<std::unique_ptr<const Curve>, common::Interval<Length>>& curve ) = 0;
 

        virtual std::pair<std::shared_ptr<const Curve>,common::Interval<Length>> DetachCurve() noexcept = 0;
 

        virtual std::pair<std::shared_ptr<const Curve>,common::Interval<Length>> GetCurve() const noexcept = 0;
 

        
        virtual void Attach( std::unique_ptr<RoadwayTwist> pTwist ) = 0;
 

        virtual std::unique_ptr<RoadwayTwist> DetachTwist() = 0;
 

        virtual RoadwayTwist& GetTwist() const noexcept = 0;
 

        
        virtual void Attach( std::shared_ptr<Sensor> pSensor, const TrackLocation& tracklocation ) = 0;
 

        virtual bool Attached( const Sensor& sensor, TrackLocation* pTrackLocation = nullptr ) const = 0;
 

        virtual void Detach( const Sensor& sensor ) noexcept = 0;
 

        virtual std::shared_ptr<Sensor> GetSensor( int idx ) const noexcept = 0;
 

        virtual int CountSensors() const = 0;
 

        
        virtual void Attach( std::shared_ptr<Signal> pSignal, const common::Interval<Length>& trackRange ) = 0;

        virtual void Attach( std::shared_ptr<Signal> pSignal, const TrackLocation& location ) = 0;
 

        virtual bool Attached( const Signal& signal, TrackRange* pTrackRange = nullptr ) const = 0;
 

        virtual void Detach( const Signal& signal ) = 0;
 

        virtual void Flip( bool flipAttached = false ) = 0;
 

        virtual void CreateEndTransitionSignal( EndType atend ) = 0;
 

        virtual void DestroyEndTransitionSignal( EndType atend ) = 0;
    };
 

    bool dclspc SetFrame( TrackBuilder& track, const spat::Frame<Length,One>& start, Length s ) noexcept;
 

    void dclspc TransformToNonEEPCurve( TrackBuilder& track );
 

    bool dclspc Strech( TrackBuilder& track, 
        spat::VectorBundle<Length,One> start, spat::VectorBundle<Length,One> end,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        common::Interval<Length> overshoot_limits = { 0_m, +infinite__length },
        const spat::Vector<One>& up = Up, 
        Length e_length = epsilon__length, Angle e_angle = epsilon__angle );
    
    bool dclspc StrechStart( TrackBuilder& track, 
        spat::Position<Length> start,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length );
    
    bool dclspc StrechStart( TrackBuilder& track, 
        spat::Position<Length> start, bool bKeepStartTangent, Length cubicOvershootStart, Length cubicOvershootEnd,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        common::Interval<Length> overshoot_limits = { 0_m, +infinite__length },
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length, Angle e_angle = epsilon__angle );
    
    bool dclspc StrechStart( TrackBuilder& track, 
        spat::VectorBundle<Length,One> start, Length cubicOvershootEnd,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        common::Interval<Length> overshoot_limits = { 0_m, +infinite__length },
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length, Angle e_angle = epsilon__angle );
    
    bool dclspc StrechEnd( TrackBuilder& track, 
        spat::Position<Length> end,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length );
    
    bool dclspc StrechEnd( TrackBuilder& track, 
        spat::Position<Length> end, bool bKeepEndTangent, Length cubicOvershootStart, Length cubicOvershootEnd,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        common::Interval<Length> overshoot_limits = { 0_m, +infinite__length },
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length, Angle e_angle = epsilon__angle );
    
    bool dclspc StrechEnd( TrackBuilder& track, 
        spat::VectorBundle<Length,One> end, Length cubicOvershootStart,
        common::Interval<Length> length_limits = {0_m,+infinite__length},
        common::Interval<Length> overshoot_limits = { 0_m, +infinite__length },
        const spat::Vector<One>& up = Up, Length e_length = epsilon__length, Angle e_angle = epsilon__angle );
 

    bool dclspc Mirror( TrackBuilder& track, 
        const spat::VectorBundle<Length,One> mirrorPlane, bool bTest = false );
 

    bool dclspc Normalize( TrackBuilder& track, bool bTest = false );
 

    void dclspc StraightenUp( TrackBuilder& track, const spat::Vector<One>& up = Up );
 

    bool dclspc Simplify( TrackBuilder& track ) noexcept;
 

    
    //std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, const Factory& factory, bool cloneCurve = false );
 
    std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, TrackBuilder& copyTrack, bool cloneCurve = false );
 
    std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, bool cloneCurve = false );
 
    //std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, const Factory& factory, common::Interval<Length> copyRange, bool cloneCurve = false );
 
    std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, TrackBuilder& copyTrack, common::Interval<Length> copyRange, bool cloneCurve = false );
 
    std::shared_ptr<TrackBuilder> dclspc CopyTrack( const TrackBuilder& originalTrack, common::Interval<Length> copyRange, bool cloneCurve = false );
 

    
    //std::vector<std::shared_ptr<TrackBuilder>> dclspc SplitTrack( const TrackBuilder& track, const Factory& factory, int numPieces = 2, bool cloneCurve = false );
    
    std::vector<std::shared_ptr<TrackBuilder>> dclspc SplitTrack( const TrackBuilder& track, int numPieces = 2, bool cloneCurve = false );
 
    //std::vector<std::shared_ptr<TrackBuilder>> dclspc SplitTrack( const TrackBuilder& track, const Factory& factory, Length atParameter, bool cloneCurve = false );
    
    std::vector<std::shared_ptr<TrackBuilder>> dclspc SplitTrack( const TrackBuilder& track, Length atParameter, bool cloneCurve = false );
 

    std::vector<std::shared_ptr<TrackBuilder>> dclspc CloseGap( 
        spat::Frame<Length,One> start, 
        spat::Frame<Length,One> end, 
        common::Interval<Length> limits,
        const spat::Vector<One>& up = Up, 
        Length e_length = epsilon__length, 
        Angle e_angle = epsilon__angle,
        bool cloneCurve = false );
 

 
    spat::VectorBundle2<Length,One> dclspc Parallel( const TrackBuilder& originalTrack, Length s, spat::Vector2D<Length> shift );

    spat::VectorBundle2<Length,One> dclspc ParallelToUp( const TrackBuilder& originalTrack, Length s, spat::Vector2D<Length> shift, spat::Vector<One> up = Up );
 

    
    std::shared_ptr<TrackBuilder> dclspc MakeParallelTrack( 
        const TrackBuilder& originalTrack, 
        common::Interval<Length> range, 
        spat::Vector2D<Length> shift = spat::Null2D<trax::Length>, 
        bool bShiftRelativeToTwistOrUp = true, 
        spat::Vector<One> up = Up, 
        Length maxDeviationLength = epsilon__length,
        Angle maxDeviationAngle = epsilon__angle );

    std::shared_ptr<TrackBuilder> dclspc MakeParallelTrackWithPolygonalChain( 
        const TrackBuilder& originalTrack, 
        common::Interval<Length> range, 
        spat::Vector2D<Length> shift = spat::Null2D<trax::Length>, 
        bool bShiftRelativeToTwistOrUp = true, 
        spat::Vector<One> up = Up,
        Length maxDeviationLength = epsilon__length, 
        common::Interval<Length> sampleDistanceLimits = { 1_m, 10_m } );

    std::shared_ptr<TrackBuilder> dclspc MakeParallelTrackWithSampledCurve( 
        const TrackBuilder& originalTrack, 
        common::Interval<Length> range, 
        spat::Vector2D<Length> shift = spat::Null2D<trax::Length>, 
        bool bShiftRelativeToTwistOrUp = true,
        spat::Vector<One> up = Up,
        Length maxDeviationLength = epsilon__length, 
        Angle maxDeviationAngle = epsilon__angle, 
        common::Interval<Length> sampleDistanceLimits = { epsilon__length, 20_m } );

    std::shared_ptr<TrackBuilder> dclspc MakeParallelTrackWithSpline(
        const TrackBuilder& originalTrack, 
        common::Interval<Length> range,
        spat::Vector2D<Length> shift,
        bool bShiftRelativeToTwistOrUp,
        spat::Vector<One> up = Up,
        Length maxDeviationLength = epsilon__length,
        common::Interval<Length> sampleDistanceLimits = { 1_m, 1000_m } );
 

// inlines:
inline Track::End::End( const std::pair<std::shared_ptr<TrackBuilder>,Track::EndType>& trackEnd ) noexcept
    : id    { trackEnd.first ? trackEnd.first->ID() : IDType{0u} }
    , type  { trackEnd.second }
{}
 
inline bool operator==( const Track::End& theone, const Track::End& theother ) noexcept{
    return theone.id == theother.id && theone.type == theother.type;
}
 
inline bool operator!=( const Track::End& theone, const Track::End& theother ) noexcept{
    return !operator==( theone, theother );
}
 
inline bool operator==( const Track::Coupling& a, const Track::Coupling& b ) noexcept{
    return  a.theOne == b.theOne &&
            a.theOther == b.theOther;
}
 
inline bool operator!=( const Track::Coupling& a, const Track::Coupling& b ) noexcept{
    return !operator==( a, b );
}
 
inline bool operator==( const Track::Overlap& a, const Track::Overlap& b ) noexcept{
    return  a.forID == b.forID &&
            a.forNear == b.forNear &&
            a.forFar == b.forFar &&
            a.withID == b.withID &&
            a.withNear == b.withNear &&
            a.withFar == b.withFar;
}
 
inline bool operator<( const Track::Overlap& a, const Track::Overlap& b ) noexcept{
    if( a.forID < b.forID )
        return true;
    if( a.forID == b.forID ){
        if( a.withID < b.withID )
            return true;
        if( a.withID == b.withID ){
            if( a.forNear < b.forNear )
                return true;
            if( a.forNear == b.forNear ){
                if( a.forFar < b.forFar )
                    return true;
                if( a.forFar == b.forFar ){
                    if( a.withNear < b.withNear )
                        return true;
                    if( a.withNear == b.withNear )
                        if( a.withFar < b.withFar )
                            return true;
                }
            }
        }
    }
 
    return false;
}
//
//inline bool operator==( const TrackBuilder& tbA, const TrackBuilder& tbB ){
//  if( !tbA.GetCurve() && tbB.GetCurve() ||
//      tbA.GetCurve() && !tbB.GetCurve() )
//      return false;
//
//  if( tbA.GetCurve() && !tbA.GetCurve()->Equal( *tbB.GetCurve() ) )
//      return false;
//
//  return  tbA.ID()                    == tbB.ID()                 &&
//          tbA.Reference( "name" )     == tbB.Reference( "name" )  &&
//          tbA.GetFrame()              == tbB.GetFrame()           &&
//          tbA.GetTwist()->Equal( tbB.GetTwist().get());
//}
//
//inline bool operator!=( const TrackBuilder& tbA, const TrackBuilder& tbB ){
//      return !(tbA == tbB);
//}
 
}