com.SIMRacingApps

Class Track

java.lang.Object

com.SIMRacingApps.Track

Direct Known Subclasses:

iRacingTrack

public class Track
extends java.lang.Object

This class contains information about a track. A track map contains points in percentage that maps to the Latitude and Longitude of the location on the track. This can be used by SIMs that do not output the actual Lat/Long. The JSON files can be found in the @{link com.SIMRacingApps.Tracks} for the different configurations. https://en.wikipedia.org/wiki/List_of_NASCAR_tracks

Since:

1.0

Author:

Jeffrey Gilliam

Copyright:

Copyright (C) 2015 - 2024 Jeffrey Gilliam

License:

Apache License 2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Track.Category An enumeration of the track category returned by the SIM.
static class	Track.SectorType An enumeration of the track sector types returned by the SIM.
static class	Track.TrackLocation An enumeration of the track locations used by the SIM.
static class	Track.Type An enumeration of the track types returned by the SIM.

Constructor Summary

Constructors

Constructor and Description
Track(SIMPlugin SIMPlugin) Class constructor to use when you have a SIMPlugin

Method Summary

Modifier and Type	Method and Description
double	_getMergePoint(double relativeTo) Returns the merging point as a percentage of where you are allowed to merge onto the track after when leaving the pits.
double	_maxPercentage()
Data	getBearing()
Data	getBearing(java.lang.String location)
Data	getBearing(java.lang.String location, java.lang.Double percentage, java.lang.String UOM) Returns the bearing of the requested position based on percentage traveled from the start/finish line.
Data	getBearing(java.lang.String location, java.lang.String percentage)
Data	getBearing(java.lang.String location, java.lang.String percentage, java.lang.String UOM)
Data	getCategory() Returns the track category as defined by Track.Category
Data	getCity() Returns the city of where the track is as reported by the SIM SIMPlugin.
Data	getCondition() Returns the track condition as reported by the SIM SIMPlugin.
Data	getConfiguration() Returns the track configuration as reported by the SIM SIMPlugin.
Data	getCountry() Returns the country code of where the track is as reported by the SIM SIMPlugin.
Data	getDescription() Returns the description of the track.
Data	getFinishLineRotation()
Data	getFinishLineRotation(java.lang.String UOM) Returns the degrees to rotate the finish line.
Data	getImage()
Data	getImage(java.lang.String type) Returns the path to the track image specified by the "type" of image.
Data	getLatitude()
Data	getLatitude(java.lang.String location)
Data	getLatitude(java.lang.String location, java.lang.Double percentage, java.lang.String UOM) Returns the Latitude of the requested position based on percentage traveled from the start/finish line.
Data	getLatitude(java.lang.String location, java.lang.String percentage)
Data	getLatitude(java.lang.String location, java.lang.String percentage, java.lang.String UOM)
Data	getLength()
Data	getLength(java.lang.String UOM) Returns the length of the track using the unit of measure the distance of this track is normally reported in.
Data	getLongitude()
Data	getLongitude(java.lang.String location)
Data	getLongitude(java.lang.String location, java.lang.Double percentage, java.lang.String UOM) Returns the Longitude of the requested position based on percentage traveled from the start/finish line.
Data	getLongitude(java.lang.String location, java.lang.String percentage)
Data	getLongitude(java.lang.String location, java.lang.String percentage, java.lang.String UOM)
java.util.Map<java.lang.String,java.lang.Object>	getMap() Returns the data map of the track as a Map<String,Object>.
Data	getName() Returns the name of the track as reported by the SIM.
Data	getNorth()
Data	getNorth(java.lang.String UOM) Returns the degrees of where North points, where zero degrees is at 3 o'clock and rotates clockwise.
Data	getPath()
Data	getPath(java.lang.String location)
Data	getPath(java.lang.String location, java.lang.String UOM) Returns the path of the track's configuration.
Data	getPitSpeedLimit()
Data	getPitSpeedLimit(java.lang.String UOM) Returns the Pit Speed Limit for this session as reported by the SIM SIMPlugin.
Data	getResolution()
Data	getResolution(java.lang.String UOM) Returns the resolution to be used with GPS mapping software for displaying the track on a map.
Data	getSectors()
Data	getSectors(java.lang.String sectorType)
Data	getSectors(java.lang.String sectorType, java.lang.String UOM) Returns an array of sector starting and ending points.
Data	getTemp()
Data	getTemp(java.lang.String UOM) Returns the current temperature of the track.
Data	getTimeZone() Returns the time zone of the track's actual location in long format (i.e.
Data	getType() Returns the track's type as defined by Track.Type
Data	getWeatherFogLevel() Returns the fog level as a percentage.
Data	getWeatherRelativeHumidity() Returns the relative humidity as a percentage.
Data	getWeatherSkies() Returns the condition of the skies, like "Partly Cloudy".
Data	getWeatherTemp()
Data	getWeatherTemp(java.lang.String UOM) Returns the current ambient temperature at the track.
Data	getWeatherWindDirection()
Data	getWeatherWindDirection(java.lang.String UOM) Returns the wind direction, where East is zero degrees at 3 o'clock.
Data	getWeatherWindSpeed()
Data	getWeatherWindSpeed(java.lang.String UOM) Returns the wind speed.
void	reload() Forces a reload of the track's JSON files.

Methods inherited from class java.lang.Object

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

Constructor Detail

Track

public Track(SIMPlugin SIMPlugin)

Class constructor to use when you have a SIMPlugin

Parameters:

SIMPlugin - An instance of a specific SIM SIMPlugin.

Method Detail

_maxPercentage

public double _maxPercentage()

reload

public void reload()

Forces a reload of the track's JSON files. Normally the JSON files are only read once and cached.

getMap

public java.util.Map<java.lang.String,java.lang.Object> getMap()

Returns the data map of the track as a Map<String,Object>. The OnTrack and OnPitRoad percentages will be from 0.0 to 100.0 with each one tenth of a percent filled in between. The format of the map is defined in JSON as:

 {
     "Latitude":    35.351669,        //center to rotate on
     "Longitude":   -80.682891,       //center to rotate on
     "Resolution":  1.9,              //meters per pixed @ 800x480
     "MergePoint":  38.5,             //percentage from finish line where you are safe to merge from pit road to the track
     "MaxPercentage": 100.0,          //Normalize the percentage for distance according to this
     "DistanceUOM": "mile",           //the unit of measure to show distance in
     "TempUOM":     "F",              //the unit of measure to show temperature in
     "SpeedUOM":    "mph",            //the unit of measure to show speed in
     "North":       166.0,            //degrees to rotate map so north points in that direction
     "FinishLine":  270.0,            //degrees to rotate the finish line, post rotation of the map. Initially zero degrees.
     "ONTRACK": {
         "0.0":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.1":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.2":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.3":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         ...
         "100.0": { "Latitude": 29.18888888,  "Longitude": -81.072 }
     },
     "ONPITROAD": {
         "0.0":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.1":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.2":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         "0.3":   { "Latitude": 29.18888888,  "Longitude": -81.072 },
         ...
         "100.0": { "Latitude": 29.18888888,  "Longitude": -81.072 }
     }
 }
 

Returns:

A Data object containing the JSON file contents of this track defined as a Map<String,Object> in a Data container..

_getMergePoint

public double _getMergePoint(double relativeTo)

Returns the merging point as a percentage of where you are allowed to merge onto the track after when leaving the pits.

Some tracks, like Bristol, have multiple merge points because it has 2 pit lanes. So the relativeTo argument should be either your pit stall location or your current location if you are exiting the pits.

Parameters:

relativeTo - The point, as a percentage, to use to find the next merge point after. Range 0.0 to 100.0.

Returns:

The merge point.

getBearing

public Data getBearing(java.lang.String location,
                       java.lang.Double percentage,
                       java.lang.String UOM)

Returns the bearing of the requested position based on percentage traveled from the start/finish line. Can return the coordinate based on 2 locations, ONTRACK and ONPITROAD. You can get the bearing at the start/finish line by passing in ONTRACK with a percentage of zero.

270 degrees is north, 0 is east, 90 is south and 180 is west.

If a SIM can return the exact bearing, then it should override this functions and return them. Otherwise, the percentage is used to approximate the position.

PATH = /Track/Bearing/(LOCATION)/(PERCENTAGE)/(UOM)

Parameters:

location - (Optional), The location of where you want the percentage to apply to, ONTRACK, or ONPITROAD. Defaults to ONTRACK.

percentage - (Optional), The percentage traveled from the start/finish line. Range 0.0 to 100.0. Defaults to 0.0.

UOM - (optional), The UOM to return the Latitude in. Defaults to degrees.

Returns:

The bearing.

getBearing

public Data getBearing(java.lang.String location,
                       java.lang.String percentage,
                       java.lang.String UOM)

getBearing

public Data getBearing(java.lang.String location,
                       java.lang.String percentage)

getBearing

public Data getBearing(java.lang.String location)

getBearing

public Data getBearing()

getCategory

public Data getCategory()

Returns the track category as defined by Track.Category

PATH = /Track/Category

Returns:

The category in a Data container.

getCity

public Data getCity()

Returns the city of where the track is as reported by the SIM SIMPlugin.

PATH = /Track/City

Returns:

The city in a Data container.

getCondition

public Data getCondition()

Returns the track condition as reported by the SIM SIMPlugin. Could be rubber build up, wetness, dirt.

PATH = /Track/Condition

Returns:

The conditions in a Data container.

getConfiguration

public Data getConfiguration()

Returns the track configuration as reported by the SIM SIMPlugin.

PATH = /Track/Configuration

Returns:

The configuration in a Data container.

getCountry

public Data getCountry()

Returns the country code of where the track is as reported by the SIM SIMPlugin.

PATH = /Track/Country

Returns:

The country code in a Data container.

getDescription

public Data getDescription()

Returns the description of the track. This is a value that can be displayed to the user.

PATH = /Track/Description

Returns:

The description of the track in a Data container.

getFinishLineRotation

public Data getFinishLineRotation(java.lang.String UOM)

Returns the degrees to rotate the finish line. Defaults to zero degrees for no rotation. Should be the angle you want to match the already rotated map based on North angle. In other words, it does not rotate with the map.

PATH = /Track/getFinishLineRotation/(UOM)

Parameters:

UOM - (Optional), The unit of measure to return, defaults to "deg".

Returns:

The degrees to Rotate in a Data container.

getFinishLineRotation

public Data getFinishLineRotation()

getImage

public Data getImage(java.lang.String type)

Returns the path to the track image specified by the "type" of image. The image will be located on the classpath. You can also use the this.class.getClassLoader().getResourceAsStream(imagepath) to have Java find the file anywhere in the classpath.

The supported types are:

• SAT = Satellite
• MAp = A Map Drawing

For example: com/SIMRacingApps/Tracks/charlotte_sat.png

PATH = /Track/Image/(type)

Parameters:

type - The type of image, "sat" or "map". Defaults to "sat".

Returns:

The image path in a Data container.

getImage

public Data getImage()

getLatitude

public Data getLatitude(java.lang.String location,
                        java.lang.Double percentage,
                        java.lang.String UOM)

Returns the Latitude of the requested position based on percentage traveled from the start/finish line. Can return the coordinate based on 3 locations, CENTER, ONTRACK and ONPITROAD. You can get the start/finish line by passing in ONTRACK with a percentage of 100.

If a SIM can return the exact coordinates, then it should override this functions and return them. Otherwise, the percentage is used to approximate the position.

PATH = /Track/Latitude/(LOCATION)/(PERCENTAGE)/(UOM)

Parameters:

location - (Optional), The location of where you want the percentage to apply to, CENTER, ONTRACK, or ONPITROAD. Defaults to CENTER.

percentage - (Optional), The percentage traveled from the start/finish line. Range 0.0 to 100.0 or MaxPercentage. Defaults to 0.0.

UOM - (optional), The UOM to return the Latitude in. Defaults to degrees.

Returns:

The Latitude.

getLatitude

public Data getLatitude(java.lang.String location,
                        java.lang.String percentage,
                        java.lang.String UOM)

getLatitude

public Data getLatitude(java.lang.String location,
                        java.lang.String percentage)

getLatitude

public Data getLatitude(java.lang.String location)

getLatitude

public Data getLatitude()

getLength

public Data getLength(java.lang.String UOM)

Returns the length of the track using the unit of measure the distance of this track is normally reported in. This is defined in the JSON file. If not defined in the JSON file, then it will default to "mile" in the United States and "km" everywhere else. You can also pass in a UOM as an optional argument.

PATH = /Track/Length/(UOM)

Parameters:

UOM - (Optional), The UOM to return the track length in. Default to track's UOM, which is based on the country it's in.

Returns:

The length of the track in a Data container.

getLength

public Data getLength()

getLongitude

public Data getLongitude(java.lang.String location,
                         java.lang.Double percentage,
                         java.lang.String UOM)

Returns the Longitude of the requested position based on percentage traveled from the start/finish line. Can return the coordinate based on 3 locations, CENTER, ONTRACK and ONPITROAD. You can get the start/finish line by passing in ONTRACK with a percentage of 100.0.

If a SIM can return the exact coordinates, then it should override this functions and return them. Otherwise, the percentage is used to approximate the position.

PATH = /Track/Longitude/(LOCATION)/(PERCENTAGE)/(UOM)

Parameters:

location - (Optional), The location of where you want the percentage to apply to, CENTER, ONTRACK, or ONPITROAD. Defaults to CENTER.

percentage - (Optional), The percentage traveled from the start/finish line. Range 0.0 to 100.0 or MaxPercentage. Defaults to 0.0.

UOM - (optional), The UOM to return the Longitude in. Defaults to degrees.

Returns:

The Longitude.

getLongitude

public Data getLongitude(java.lang.String location,
                         java.lang.String percentage,
                         java.lang.String UOM)

getLongitude

public Data getLongitude(java.lang.String location,
                         java.lang.String percentage)

getLongitude

public Data getLongitude(java.lang.String location)

getLongitude

public Data getLongitude()

getName

public Data getName()

Returns the name of the track as reported by the SIM. This should include a specific configuration. Clients should make no assumptions about the format of this name. Use it to display only.

For example: atlanta_qualoval

PATH = /Track/Name

Returns:

The name of the track in a Data container.

getNorth

public Data getNorth(java.lang.String UOM)

Returns the degrees of where North points, where zero degrees is at 3 o'clock and rotates clockwise. If North is not defined in the track.json file, then it defaults to 270deg, straight up at 12 o'clock.

PATH = /Track/North/(UOM)

Parameters:

UOM - (Optional), The unit of measure to return the direction of north in, defaults to "deg".

Returns:

The degrees to North in a Data container.

getNorth

public Data getNorth()

getPath

public Data getPath(java.lang.String location,
                    java.lang.String UOM)

Returns the path of the track's configuration. The format follows how SVG defines a path with a Start, MoveTo, End. If needed, there could be more than one segment if it is not continuous.

The results are returned in the following format. Type values are: -1.0 move to, 0.0 line to. NOTE: I use to use the close Type, but not all Start/Finish lines are at the same place on all tracks.

 [
     { "Type": -1.0,  "Lat": 0.0, "Lon": 0.0 },
     { "Type":  0.0,  "Lat": 0.0, "Lon": 0.0 },
 ]
 

PATH = /Track/Path

Parameters:

location - (Optional) The location of the track to return the path to. Can be ONTRACK, ONPITROAD. Defaults to ONTRACK.

UOM - (Optional) The unit of measure to return the path in, default to the track's UOM.

Returns:

The path of the track in a Data container as ArrayList<Map<String,Double>>.

getPath

public Data getPath(java.lang.String location)

getPath

public Data getPath()

getPitSpeedLimit

public Data getPitSpeedLimit(java.lang.String UOM)

Returns the Pit Speed Limit for this session as reported by the SIM SIMPlugin.

PATH = /Track/PitSpeedLimit/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return the speed limit in, default to the track's UOM.

Returns:

The Pit Speed Limit

getPitSpeedLimit

public Data getPitSpeedLimit()

getResolution

public Data getResolution(java.lang.String UOM)

Returns the resolution to be used with GPS mapping software for displaying the track on a map. The resolution is the meters per pixel based on the standard map size of 800x480. Defaults to 1.9 if the JSON file does not define it.

Parameters:

UOM - (Optional) The unit of measure to return the resolution in, defaults to meters.

Returns:

The Resolution in a Data container.

getResolution

public Data getResolution()

getSectors

public Data getSectors(java.lang.String sectorType,
                       java.lang.String UOM)

Returns an array of sector starting and ending points. If SectorType is PERCENTAGE, then with the index starting at zero, the even numbered indexes are the starting points and are inclusive. The odd numbered indexes are the ending points and are exclusive. The number of sectors can be derived by dividing the number of array entries by 2. If SectorType is COORDINATES, then with the index starting at zero, indexes are as follows, (0=startingLat, 1=startingLon, 2=endingLat, 3=endingLon). This pattern repeats throughout the array. The number of sectors can be derived by dividing the number of array entries by 4. If there are no sectors defined, an empty array is returned with a length of zero.

PATH = /Track/Sectors/(SECTORTYPE)/(UOM)

Parameters:

sectorType - (optional) Indicates the type of the values being returned. Valid values are Track.SectorType, PERCENTAGE, COORDINATES. Defaults PERCENTAGE.

UOM - (optional) Specifies the unit of measure to return. %, RAD, DEG. Default is % and DEG.

Returns:

An array of sectors in a Data container.

getSectors

public Data getSectors(java.lang.String sectorType)

getSectors

public Data getSectors()

getTemp

public Data getTemp(java.lang.String UOM)

Returns the current temperature of the track. The location of this temperature is SIM specific. Should not be used to understand where grip is best on the track. In most cases you will only want to display it.

PATH = /Track/Temp/(UOM)

Parameters:

UOM - (Optional) The unit of measure to convert the temperature in, default to track's UOM.

Returns:

The temperature in a Data container.

getTemp

public Data getTemp()

getTimeZone

public Data getTimeZone()

Returns the time zone of the track's actual location in long format (i.e. America/New_York). The State is set to the short format (i.e. EST). If no track is loaded, it returns the users current time zone.

Returns:

The time zone of the track in a Data container.

getType

public Data getType()

Returns the track's type as defined by Track.Type

PATH = /Track/Type

Returns:

The type in a Data container.

getWeatherFogLevel

public Data getWeatherFogLevel()

Returns the fog level as a percentage.

PATH = /Track/WeatherFogLevel

Returns:

The fog level in a Data container.

getWeatherRelativeHumidity

public Data getWeatherRelativeHumidity()

Returns the relative humidity as a percentage.

PATH = /Track/WeatherRelativeHumidity

Returns:

The relative humidity in a Data container.

getWeatherSkies

public Data getWeatherSkies()

Returns the condition of the skies, like "Partly Cloudy".

PATH = /Track/WeatherSkies

Returns:

The sky condition in a Data container.

getWeatherTemp

public Data getWeatherTemp(java.lang.String UOM)

Returns the current ambient temperature at the track.

PATH = /Track/WeatherTemp/(UOM)

Parameters:

UOM - (Optional) The unit of measure to convert the temperature in, default to track's UOM.

Returns:

The temperature in a Data container.

getWeatherTemp

public Data getWeatherTemp()

getWeatherWindDirection

public Data getWeatherWindDirection(java.lang.String UOM)

Returns the wind direction, where East is zero degrees at 3 o'clock. If the UOM is "TEXT", then returns one of the following: N, NE, W, SW, S, SE, E, NE.

PATH = /Track/WeatherWindDirection/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return the wind direction in, defaults to "deg".

Returns:

The wind direction in a Data container.

getWeatherWindDirection

public Data getWeatherWindDirection()

getWeatherWindSpeed

public Data getWeatherWindSpeed(java.lang.String UOM)

Returns the wind speed.

PATH = /Track/WeatherWindSpeed/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return the wind speed in, defaults to track's UOM for Pit Road Speed.

Returns:

The wind speed in a Data container.

getWeatherWindSpeed

public Data getWeatherWindSpeed()