Package jmri.jmrit.roster

Class RosterSpeedProfile

java.lang.Object

jmri.jmrit.roster.RosterSpeedProfile

public class RosterSpeedProfile
extends java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	RosterSpeedProfile.SpeedSetting
static class	RosterSpeedProfile.SpeedStep

Field Summary

Fields

Modifier and Type	Field	Description
static float	MMS_TO_KPH	Speed conversion Millimetres per second to Kilometres per hour.
static float	MMS_TO_MPH	Speed conversion Millimetres per second to Miles per hour.

Constructor Summary

Constructors

Constructor	Description
RosterSpeedProfile(RosterEntry re)	Create a new RosterSpeedProfile.

Method Summary

Modifier and Type	Method	Description
(package private) float	calculateInitialOverRun(float distance)
(package private) void	calculateStepDetails(float speedStep, float distance, boolean andStop)
void	cancelSpeedChange()	This method is called to cancel the existing change in speed.
void	changeLocoSpeed(DccThrottle t, float distance, float requestedSpeed)	Set speed of a throttle.
void	changeLocoSpeed(DccThrottle t, Block blk, float speed)	Set speed of a throttle.
void	changeLocoSpeed(DccThrottle t, Block blk, float speed, float usePercentage)	Set speed of a throttle.
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.
void	changeLocoSpeed(DccThrottle t, Section sec, float speed, float usePercentage)	Set speed of a throttle.
void	clearCurrentProfile()
static java.lang.String	convertMMSToScaleSpeedWithUnits(float mms)	Returns the scale speed format as a string with the units added given MilliMetres per Second.
float	convertScaleSpeedToMMS(float scaleSpeed)	MilliMetres per Second given scale speed.
java.lang.String	convertThrottleSettingToScaleSpeedWithUnits(float throttleSetting, boolean isForward)	Returns the scale speed format as a string with the units added given a throttle setting. and direction.
void	deleteStep(java.lang.Integer step)
(package private) void	finishChange()	reset everything back to default once the change has finished.
float	getDistanceTravelled(boolean isForward, float speedStep, float duration)	Get the approximate distance a loco may travel a given duration at a given speed step.
float	getDurationOfTravelInSeconds(boolean isForward, float speedStep, int distance)	Get the approximate time a loco may travel a given distance at a given speed step.
float	getForwardSpeed(float speedStep)	return the forward speed in milli-meters per second for a given percentage throttle
float	getOverRunTimeForward()
float	getOverRunTimeReverse()
int	getProfileSize()	Get the number of SpeedSteps.
java.util.TreeMap<java.lang.Integer,RosterSpeedProfile.SpeedStep>	getProfileSpeeds()
float	getReverseSpeed(float speedStep)	return the reverse speed in millimetres per second for a given percentage throttle
RosterEntry	getRosterEntry()	Get the RosterEntry associated with the profile.
float	getSpeed(float speedStep, boolean isForward)	Get track speed in millimeters per second from throttle setting
RosterSpeedProfile.SpeedStep	getSpeedStep(float speed)
protected java.util.List<RosterSpeedProfile.SpeedSetting>	getSpeedStepTrace()	Gets the speed step trace array.
float	getThrottleSetting(float speed, boolean isForward)	Get the throttle setting to achieve a track speed
float	getThrottleSettingFromSignalMapSpeed(float signalMapSpeed, boolean isForward)	Converts from signal map speed to a throttle setting.
boolean	hasForwardSpeeds()	Check if the Speed Profile contains Forward Speeds.
boolean	hasReverseSpeeds()	Check if the Speed Profile contains Reverse Speeds.
void	load(org.jdom2.Element e)
float	mmsToScaleSpeed(float mms)	Returns the scale speed as a numeric.
float	mmsToScaleSpeed(float mms, boolean factorFastClock)	Returns the scale speed.
float	MMSToScaleSpeed(float mms)	Deprecated, for removal: This API element is subject to removal in a future version. use mmsToScaleSpeed(float mms)
void	setExtraInitialDelay(float eDelay)
void	setForwardSpeed(float speedStep, float forward)
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.
void	setMinMaxLimits(float minReliableOperatingSpeed, float maxOperatingSpeed)
(package private) void	setNextStep()
void	setOverRunTimeForward(float dt)
void	setOverRunTimeReverse(float dt)
void	setReverseSpeed(float speedStep, float reverse)
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.
void	setSpeed(int speedStep, float forward, float reverse)	Set the speed for the given speed step.
protected void	setTestMode(boolean value)	place / remove SpeedProfile from test mode.
void	store(org.jdom2.Element e)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MMS_TO_MPH

public static final float MMS_TO_MPH

Speed conversion Millimetres per second to Miles per hour.

See Also:

Constant Field Values

MMS_TO_KPH

public static final float MMS_TO_KPH

Speed conversion Millimetres per second to Kilometres per hour.

See Also:

Constant Field Values

Constructor Detail

RosterSpeedProfile

public RosterSpeedProfile(RosterEntry re)

Create a new RosterSpeedProfile.

Parameters:

re - the Roster Entry associated with the profile.

Method Detail

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(java.lang.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

protected void setTestMode(boolean value)

place / remove SpeedProfile from test mode. reinitializes speedstep trace array

Parameters:

value - true/false

getSpeedStepTrace

protected java.util.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 java.lang.String convertMMSToScaleSpeedWithUnits(float mms)

Returns the scale speed format as a 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 java.lang.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

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)

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 java.util.TreeMap<java.lang.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