Package jmri.jmrit.roster

Class RosterSpeedProfile

java.lang.Object
jmri.jmrit.roster.RosterSpeedProfile
public class RosterSpeedProfile extends Object
A class to store a speed profile for a given loco. The speed steps against the profile are on a scale of 0 to 1000, this equates to the float speed x 1000. This allows a single profile to cover different throttle speed step settings. A profile generated for a loco using 28 steps can be used for a throttle with 126 steps.

  • Field Details

  • Constructor Details

    • RosterSpeedProfile

      public RosterSpeedProfile(RosterEntry re)
      Create a new RosterSpeedProfile.
      Parameters:
      re - the Roster Entry associated with the profile.

  • Method Details

    • getRosterEntry

      public RosterEntry getRosterEntry()
      Get the RosterEntry associated with the profile.
      Returns:
      the RosterEntry.

    • getOverRunTimeForward

      public float getOverRunTimeForward()

    • setOverRunTimeForward

      public void setOverRunTimeForward(float dt)

    • getOverRunTimeReverse

      public float getOverRunTimeReverse()

    • setOverRunTimeReverse

      public void setOverRunTimeReverse(float dt)

    • clearCurrentProfile

      public void clearCurrentProfile()

    • deleteStep

      public void deleteStep(Integer step)

    • hasForwardSpeeds

      public boolean hasForwardSpeeds()
      Check if the Speed Profile contains Forward Speeds.
      Returns:
      true if forward speeds are present, else false.

    • hasReverseSpeeds

      public boolean hasReverseSpeeds()
      Check if the Speed Profile contains Reverse Speeds.
      Returns:
      true if reverse speeds are present, else false.

    • setTestMode

      public void setTestMode(boolean value)
      place / remove SpeedProfile from test mode. reinitializes speedstep trace array
      Parameters:
      value - true/false

    • getSpeedStepTrace

      public List<RosterSpeedProfile.SpeedSetting> getSpeedStepTrace()
      Gets the speed step trace array.
      Returns:
      speedstep trace array

    • mmsToScaleSpeed

      public float mmsToScaleSpeed(float mms, boolean factorFastClock)
      Returns the scale speed. If Warrant preferences are not a speed, value returns unchanged.
      Parameters:
      mms - MilliMetres per second.
      factorFastClock - true to factor in the Fast Clock ratio, else false.
      Returns:
      scale speed in units specified by Warrant Preferences, unchanged if Warrant preferences are not a speed.

    • MMSToScaleSpeed

      @Deprecated(since="5.9.6", forRemoval=true) public float MMSToScaleSpeed(float mms)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use mmsToScaleSpeed(float mms)
      Returns the scale speed as a numeric. If Warrant preferences are not a speed, value returns unchanged.
      Parameters:
      mms - MilliMetres per second
      Returns:
      scale speed in units specified by Warrant Preferences, unchanged if Warrant preferences are not a speed.

    • mmsToScaleSpeed

      public float mmsToScaleSpeed(float mms)
      Returns the scale speed as a numeric. If Warrant preferences are not a speed, value returns unchanged. Does not factor Fast Clock ratio.
      Parameters:
      mms - MilliMetres per second
      Returns:
      scale speed in units specified by Warrant Preferences, unchanged if Warrant preferences are not a speed.

    • convertMMSToScaleSpeedWithUnits

      public static String convertMMSToScaleSpeedWithUnits(float mms)
      Returns the scale speed format as I18N string with the units added given MilliMetres per Second. If the warrant preference is a percentage of normal or throttle will use metres per second. The Fast Clock Ratio is not used in the calculation.
      Parameters:
      mms - MilliMetres per second
      Returns:
      a string with scale speed and units

    • convertThrottleSettingToScaleSpeedWithUnits

      public String convertThrottleSettingToScaleSpeedWithUnits(float throttleSetting, boolean isForward)
      Returns the scale speed format as a string with the units added given a throttle setting. and direction. The Fast Clock Ratio is not used in the calculation.
      Parameters:
      throttleSetting - as percentage of 1.0
      isForward - true or false
      Returns:
      a string with scale speed and units

    • convertScaleSpeedToMMS

      public float convertScaleSpeedToMMS(float scaleSpeed)
      MilliMetres per Second given scale speed. The Fast Clock Ratio is not used in the calculation.
      Parameters:
      scaleSpeed - in MPH or KPH
      Returns:
      MilliMetres per second

    • getThrottleSettingFromSignalMapSpeed

      public float getThrottleSettingFromSignalMapSpeed(float signalMapSpeed, boolean isForward)
      Converts from signal map speed to a throttle setting. The Fast Clock Ratio is not used in the calculation.
      Parameters:
      signalMapSpeed - value from warrants preferences
      isForward - direction of travel
      Returns:
      throttle setting

    • setSpeed

      public void setSpeed(int speedStep, float forward, float reverse)
      Set the speed for the given speed step.
      Parameters:
      speedStep - the speed step to set
      forward - speed in meters per second for running forward at speedStep
      reverse - speed in meters per second for running in reverse at speedStep

    • getSpeedStep

      public RosterSpeedProfile.SpeedStep getSpeedStep(float speed)

    • setForwardSpeed

      public void setForwardSpeed(float speedStep, float forward)

    • setForwardSpeed

      public void setForwardSpeed(float throttleSetting, float speed, float speedIncrement)
      Merge raw throttleSetting value with an existing profile SpeedStep if key for the throttleSetting is within the speedIncrement of the SpeedStep.
      Parameters:
      throttleSetting - raw throttle setting value
      speed - track speed
      speedIncrement - throttle's speed step increment.

    • setReverseSpeed

      public void setReverseSpeed(float throttleSetting, float speed, float speedIncrement)
      Merge raw throttleSetting value with an existing profile SpeedStep if key for the throttleSetting is within the speedIncrement of the SpeedStep.
      Parameters:
      throttleSetting - raw throttle setting value
      speed - track speed
      speedIncrement - throttle's speed step increment.

    • setReverseSpeed

      public void setReverseSpeed(float speedStep, float reverse)

    • getForwardSpeed

      public float getForwardSpeed(float speedStep)
      return the forward speed in milli-meters per second for a given percentage throttle
      Parameters:
      speedStep - which is actual percentage throttle
      Returns:
      MilliMetres per second using straight line interpolation for missing points

    • getReverseSpeed

      public float getReverseSpeed(float speedStep)
      return the reverse speed in millimetres per second for a given percentage throttle
      Parameters:
      speedStep - percentage of throttle 0.nnn
      Returns:
      millimetres per second

    • getDurationOfTravelInSeconds

      public float getDurationOfTravelInSeconds(boolean isForward, float speedStep, int distance)
      Get the approximate time a loco may travel a given distance at a given speed step.
      Parameters:
      isForward - true if loco is running forward; false otherwise
      speedStep - the desired speed step
      distance - the desired distance in millimeters
      Returns:
      the approximate time in seconds

    • getDistanceTravelled

      public float getDistanceTravelled(boolean isForward, float speedStep, float duration)
      Get the approximate distance a loco may travel a given duration at a given speed step.
      Parameters:
      isForward - true if loco is running forward; false otherwise
      speedStep - the desired speed step
      duration - the desired time in seconds
      Returns:
      the approximate distance in millimeters

    • planStopToZeroOverDistance

      public void planStopToZeroOverDistance(DccThrottle t, float distanceMm)
      Plan and execute a stop-to-zero over a given distance (actual millimetres).
      Parameters:
      t - The DccThrottle to drive
      distanceMm - Distance in mm (>= 0)

    • planStopToZeroOverDistance

      public void planStopToZeroOverDistance(DccThrottle t, float distanceMm, float speedFactor)
      Plan and execute a stop-to-zero over a given distance (actual millimetres), with an optional external speed factor pre-divide (see AutoActiveTrain behaviour).
      Parameters:
      t - The DccThrottle to drive
      distanceMm - Distance in mm (>= 0)
      speedFactor - If > 0, throttle commands are divided by this factor before enqueuing.

    • planApproachToMinOverDistanceThenStopBySensor

      public void planApproachToMinOverDistanceThenStopBySensor(DccThrottle t, float distanceMm, Sensor stopSensor)
      Plan and execute an approach to the minimum reliable operating speed over the given distance, then stop when the supplied sensor transitions to ACTIVE.
      Parameters:
      t - The DccThrottle to drive
      distanceMm - Distance in mm (>= 0)
      stopSensor - The sensor on which to stop (must not be null)

    • planApproachToMinOverDistanceThenStopBySensor

      public void planApproachToMinOverDistanceThenStopBySensor(DccThrottle t, float distanceMm, Sensor stopSensor, float speedFactor)
      Plan and execute an approach to the minimum reliable operating speed over the given distance, then stop when the supplied sensor transitions to ACTIVE. Supports optional speed factor pre-divide.
      Parameters:
      t - The DccThrottle to drive
      distanceMm - Distance in mm (>= 0)
      stopSensor - The sensor on which to stop (must not be null)
      speedFactor - If > 0, throttle commands are divided by this factor before enqueuing.

    • setMinCommandIntervalMs

      public void setMinCommandIntervalMs(int ms)
      Set the minimum command interval (ms) used by the distance/physics planners. Values <= 0 revert to the default. Values less than DEFAULT_MIN_COMMAND_INTERVAL_MS are clamped up to the default.
      Parameters:
      ms - Minimum interval in milliseconds.

    • finishChange

      void finishChange()
      reset everything back to default once the change has finished.

    • setExtraInitialDelay

      public void setExtraInitialDelay(float eDelay)

    • setMinMaxLimits

      public void setMinMaxLimits(float minReliableOperatingSpeed, float maxOperatingSpeed)

    • setMinMaxLimitsKmh

      public void setMinMaxLimitsKmh(float minReliableOperatingSpeed, float maxOperatingSpeed, float maxSpeedScaleKmh, float layoutScaleRatio, boolean isForward)
      Set min/max throttle limits, optionally enforcing a scale km/h cap. If maxSpeedScaleKmh == 0.0f, the percent maxOperatingSpeed takes precedence (no effect). If maxSpeedScaleKmh > 0.0f, we convert the km/h cap to an equivalent throttle% using the roster profile and the layout scale ratio, then take the minimum of that and the percent cap.
      Parameters:
      minReliableOperatingSpeed - lowest throttle % the loco reliably moves (0..1)
      maxOperatingSpeed - percent cap (0..1)
      maxSpeedScaleKmh - scale km/h cap; 0.0f means "unused"
      layoutScaleRatio - layout scale ratio (full-scale / model), e.g. 87.0 for HO
      isForward - direction of travel

    • changeLocoSpeed

      public void changeLocoSpeed(DccThrottle t, Block blk, float speed)
      Set speed of a throttle.
      Parameters:
      t - the throttle to set
      blk - the block used for length details
      speed - the speed to set

    • changeLocoSpeed

      public void changeLocoSpeed(DccThrottle t, Section sec, float speed, float usePercentage)
      Set speed of a throttle.
      Parameters:
      t - the throttle to set
      sec - the section used for length details
      speed - the speed to set
      usePercentage - the percentage of the block to be used for stopping

    • changeLocoSpeed

      public void changeLocoSpeed(DccThrottle t, Block blk, float speed, float usePercentage)
      Set speed of a throttle.
      Parameters:
      t - the throttle to set
      blk - the block used for length details
      speed - the speed to set
      usePercentage - the percentage of the block to be used for stopping

    • changeLocoSpeed

      public void changeLocoSpeed(DccThrottle t, Section sec, float speed)
      Set speed of a throttle to a speeed set by a float, using the section for the length details Set speed of a throttle.
      Parameters:
      t - the throttle to set
      sec - the section used for length details
      speed - the speed to set

    • changeLocoSpeed

      public void changeLocoSpeed(DccThrottle t, float distance, float requestedSpeed)
      Set speed of a throttle.
      Parameters:
      t - the throttle to set
      distance - the distance in meters
      requestedSpeed - the speed to set

    • calculateStepDetails

      void calculateStepDetails(float speedStep, float distance, boolean andStop)

    • calculateInitialOverRun

      float calculateInitialOverRun(float distance)

    • cancelSpeedChange

      public void cancelSpeedChange()
      This method is called to cancel the existing change in speed.

    • setNextStep

      void setNextStep()

    • store

      public void store(org.jdom2.Element e)

    • load

      public void load(org.jdom2.Element e)

    • getProfileSize

      public int getProfileSize()
      Get the number of SpeedSteps. If there are too few SpeedSteps, it may be difficult to get reasonable distances and speeds over a large range of throttle settings.
      Returns:
      the number of Speed Steps in the profile.

    • getProfileSpeeds

      public TreeMap<Integer,RosterSpeedProfile.SpeedStep> getProfileSpeeds()

    • getThrottleSetting

      public float getThrottleSetting(float speed, boolean isForward)
      Get the throttle setting to achieve a track speed
      Parameters:
      speed - desired track speed in mm/sec
      isForward - direction
      Returns:
      throttle setting

    • getSpeed

      public float getSpeed(float speedStep, boolean isForward)
      Get track speed in millimeters per second from throttle setting
      Parameters:
      speedStep - throttle setting
      isForward - direction
      Returns:
      track speed

    • runPhysicsAccelerationToTargetThrottle

      public void runPhysicsAccelerationToTargetThrottle(DccThrottle t, float targetThrottlePct, float driverPowerPercent, float additionalWeightTonnes, float rollingResistanceCoeff, float layoutScaleRatio, float speedFactor)
      Physics-based acceleration to a target throttle percent (0..1). Builds and runs a throttle/time schedule using this profile's stepQueue/stopTimer.
      Parameters:
      t - The DccThrottle to drive (must not be null)
      targetThrottlePct - Desired throttle percent [0..1]
      driverPowerPercent - Driver power/regulator percent [0..1] (limits applied power/TE during acceleration)
      additionalWeightTonnes - Extra consist mass in metric tonnes (>= 0)
      rollingResistanceCoeff - Rolling resistance coefficient c_rr (>= 0), e.g., ~0.002
      layoutScaleRatio - Layout scale ratio (full-scale / model), e.g., 87.0 for HO
      speedFactor - If > 0, throttle commands are divided by this factor before enqueuing