agi.foundation.propagators

(agi.foundation.models-2024r1.jar)

Class TwoLineElementSet

java.lang.Object

agi.foundation.propagators.Sgp4Elements

agi.foundation.propagators.TwoLineElementSet

All Implemented Interfaces:

ICloneWithContext

public class TwoLineElementSet
extends Sgp4Elements

A NORAD two-line element set (TLE). Note that the precision of most TLEs is limited by the string representations in the TLE. The resulting ephemeris has a precision on the order of kilometers. When creating a TLE based on orbital elements, it is important to note that information will be lost when converting precise elements into a string representation.

The following example shows how to create a TLE from a string and then use it to create an Sgp4Propagator:

String tleString =
        "1 20724U 90068A   02173.73395695 -.00000086  00000-0  00000-0 0  1771\n" +
        "2 20724  56.1487  21.0845 0183651 226.6216 131.8780  2.00562381 85500\n";
TwoLineElementSet tle = new TwoLineElementSet(tleString);
Sgp4Propagator propagator = new Sgp4Propagator(tle);

Warning: If the EphemerisType (get / set) is 4, the TLE field for BStar (get / set) is actually the ballistic coefficient (Coefficient of drag times area over mass), the TLE field for MeanMotionDotDot (get / set) is actually the AGOM (Area times coefficient of solar radiation pressure over mass), and Sgp4Propagator will throw an exception if the TLE is input.

Constructor Summary

Constructors

Constructor and Description
TwoLineElementSet() Initializes a new Two Line Element Set with default parameters.
TwoLineElementSet(Sgp4Elements elements, String name, String satelliteNumber, String classification, String internationalDesignator, double meanMotionDot, double meanMotionDotDot, int elementNumber, int revolutions) Initializes a new Two Line Element Set (TLE) from a set of Sgp4Elements and additional meta-data contained in the TLE format.
TwoLineElementSet(String tle) Initializes a new Two Line Element Set from a string representation of the TLE.
TwoLineElementSet(String tle, boolean verifyChecksums) Initializes a new Two Line Element Set from a string representation of the TLE and optionally verifies the checksums.
TwoLineElementSet(String tle, boolean verifyChecksums, char[] whiteSpaceCharacters) Initializes a new Two Line Element Set from a string representation of the TLE and optionally verifies the checksums.
TwoLineElementSet(TwoLineElementSet existingInstance) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
Object	clone(CopyContext context) Clones this object using the specified context.
static ArrayList<TwoLineElementSet>	downloadTles(String satelliteIdentifier, JulianDate startDate, JulianDate stopDate) Downloads TLE data for a given satellite from an AGI server.
static ArrayList<TwoLineElementSet>	downloadTles(String satelliteIdentifier, JulianDate startDate, JulianDate stopDate, Proxy proxy) Downloads TLE data for a given satellite from an AGI server.
int	getChecksumLine1() Gets the checksum for line 1.
int	getChecksumLine2() Gets the checksum for line 2.
String	getClassification() Gets the classification.
int	getElementNumber() Gets the element number
int	getEphemerisType() Gets the ephemeris type.
JulianDate	getEpoch() Gets the epoch at which these initial conditions are defined.
String	getInternationalDesignator() Gets the international designator
double	getMeanMotionDot() Gets the first derivative of mean motion divided by two, in revolutions per day squared.
double	getMeanMotionDotDot() Gets the second derivative of mean motion divided by six, in revolutions per day cubed.
String	getName() Gets the spacecraft name
double	getRawEpoch() Gets the epoch at which these initial conditions are defined, represented in the standard form: YYDDD.DDDD.
int	getRevolutionNumber() Gets the revolution number at epoch.
String	getSatelliteNumber() Gets the satellite number.
void	setChecksumLine1(int value) Sets the checksum for line 1.
void	setChecksumLine2(int value) Sets the checksum for line 2.
void	setClassification(String value) Sets the classification.
void	setElementNumber(int value) Sets the element number
void	setEphemerisType(int value) Sets the ephemeris type.
void	setEpoch(JulianDate value) Sets the epoch at which these initial conditions are defined.
void	setInternationalDesignator(String value) Sets the international designator
void	setMeanMotionDot(double value) Sets the first derivative of mean motion divided by two, in revolutions per day squared.
void	setMeanMotionDotDot(double value) Sets the second derivative of mean motion divided by six, in revolutions per day cubed.
void	setName(String value) Sets the spacecraft name
void	setRawEpoch(double value) Sets the epoch at which these initial conditions are defined, represented in the standard form: YYDDD.DDDD.
void	setRevolutionNumber(int value) Sets the revolution number at epoch.
void	setSatelliteNumber(String value) Sets the satellite number.
String	toTleString() Returns a TLE string representing this TwoLineElementSet in the standard NORAD format, described by CelesTrak.
String	toTleStringLine0() Returns line 0 of the TLE represented in standard NORAD format, described by CelesTrak.
String	toTleStringLine1() Returns line 1 of the TLE represented in standard NORAD format, described by CelesTrak.
String	toTleStringLine2() Returns line 2 of the TLE represented in standard NORAD format, described by CelesTrak.
static boolean	tryConvertAlpha5SatelliteCatalogNumbersToIntegers(String alphaFiveSatelliteCatalogNumberString, String[] intSatelliteCatalogNumberString) Tries to convert an Alpha-5 satellite catalog number into its corresponding integer representation.
static boolean	tryConvertIntegerSatelliteCatalogNumbersToAlpha5(String intSatelliteCatalogNumberString, String[] alphaFiveSatelliteCatalogNumberString) Tries to convert an integer satellite catalog number into its corresponding Alpha-5 representation.
static boolean	verifyChecksum(String line) Verifies the checksum of the specified TLE line.

Methods inherited from class agi.foundation.propagators.Sgp4Elements

getArgumentOfPerigee, getBStar, getEccentricity, getInclination, getMeanAnomaly, getMeanMotion, getRightAscensionOfAscendingNode, getSwitchingMethod, setArgumentOfPerigee, setBStar, setEccentricity, setInclination, setMeanAnomaly, setMeanMotion, setRightAscensionOfAscendingNode, setSwitchingMethod

Methods inherited from class java.lang.Object

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

Constructor Detail

TwoLineElementSet

public TwoLineElementSet()

Initializes a new Two Line Element Set with default parameters.

TwoLineElementSet

public TwoLineElementSet(@Nonnull
                         String tle)

Initializes a new Two Line Element Set from a string representation of the TLE. An invalid checksum value will be silently ignored.

Parameters:

tle - The TLE represented in the standard format.

Throws:

ArgumentNullException - Thrown when tle is null.

ArgumentException - Thrown when tle contains less than two lines, or when tle has an invalid format for line 1 or line 2.

TwoLineElementSet

public TwoLineElementSet(@Nonnull
                         String tle,
                         boolean verifyChecksums)

Initializes a new Two Line Element Set from a string representation of the TLE and optionally verifies the checksums.

Parameters:

tle - The TLE represented in the standard format.

verifyChecksums - true to verify the checksums and throw an exception if they are invalid. false to ignore the checksums.

Throws:

ArgumentNullException - Thrown when tle is null.

ArgumentException - Thrown when tle contains more than two lines, or when verifyChecksums is true and tle has an invalid checksum for line 1 or line 2, or when tle has an invalid format for line 1 or line 2.

TwoLineElementSet

public TwoLineElementSet(@Nonnull
                         String tle,
                         boolean verifyChecksums,
                         @Nonnull
                         char[] whiteSpaceCharacters)

Initializes a new Two Line Element Set from a string representation of the TLE and optionally verifies the checksums.

Parameters:

tle - The TLE represented in the standard format.

verifyChecksums - true to verify the checksums and throw an exception if they are invalid. false to ignore the checksums.

whiteSpaceCharacters - An array of Unicode characters to be treated as white space within the TLE string.

Throws:

ArgumentNullException - Thrown when tle or whiteSpaceCharacters is null.

ArgumentException - Thrown when tle contains less than two lines, or when verifyChecksums is true and tle has an invalid checksum for line 1 or line 2, or when tle has an invalid format for line 1 or line 2.

TwoLineElementSet

public TwoLineElementSet(@Nonnull
                         Sgp4Elements elements,
                         String name,
                         String satelliteNumber,
                         String classification,
                         String internationalDesignator,
                         double meanMotionDot,
                         double meanMotionDotDot,
                         int elementNumber,
                         int revolutions)

Initializes a new Two Line Element Set (TLE) from a set of Sgp4Elements and additional meta-data contained in the TLE format.

Parameters:

elements - The elements specifying the essential orbit ephemeris data.

name - The name of the satellite to appear on the line just prior to the TLE.

satelliteNumber - The NORAD satellite catalog number, as a string.

classification - The single character classification for the satellite. All civilian space objects are classified with 'U' for 'Unclassified'.

internationalDesignator - The international catalog number assigned by the World Data Center-A for Rockets and Satellites.

meanMotionDot - The first time derivative of the mean motion at epoch.

meanMotionDotDot - The second time derivative of the mean motion at epoch.

elementNumber - A number assigned to indicate the number of times this ephemeris has been regenerated.

revolutions - The number of times the spacecraft has passed through its ascending node (since launch).

Throws:

ArgumentNullException - Thrown when elements is null.

TwoLineElementSet

public TwoLineElementSet(@Nonnull
                         TwoLineElementSet existingInstance)

Initializes a new instance as a copy of an existing instance.

Parameters:

existingInstance - The existing instance to copy.

Throws:

ArgumentNullException - Thrown when existingInstance is null.

Method Detail

clone

public Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Overrides:

clone in class Sgp4Elements

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

getEpoch

@Nonnull
public JulianDate getEpoch()

Gets the epoch at which these initial conditions are defined. Note: The epoch will only be represented to the precision of the TwoLineElementSet format from the RawEpoch (get / set). For greater precision, use Sgp4Elements directly.

Overrides:

getEpoch in class Sgp4Elements

setEpoch

public void setEpoch(@Nonnull
                     JulianDate value)

Sets the epoch at which these initial conditions are defined. Note: The epoch will only be represented to the precision of the TwoLineElementSet format from the RawEpoch (get / set). For greater precision, use Sgp4Elements directly.

Overrides:

setEpoch in class Sgp4Elements

getRawEpoch

public double getRawEpoch()

Gets the epoch at which these initial conditions are defined, represented in the standard form: YYDDD.DDDD. Note: this will be represented to only the precision of the TwoLineElementSet format. For greater precision, use Sgp4Elements directly.

Overrides:

getRawEpoch in class Sgp4Elements

setRawEpoch

public void setRawEpoch(double value)

Sets the epoch at which these initial conditions are defined, represented in the standard form: YYDDD.DDDD. Note: this will be represented to only the precision of the TwoLineElementSet format. For greater precision, use Sgp4Elements directly.

Overrides:

setRawEpoch in class Sgp4Elements

toTleStringLine0

@Nonnull
public final String toTleStringLine0()

Returns line 0 of the TLE represented in standard NORAD format, described by CelesTrak. Line 0 contains the Name (get / set) padded to 24 characters. The returned line does not contain any new line or line break characters.

Returns:

Line 0 of the TLE string.

Throws:

PropertyInvalidException - The properties of this instance cannot be represented as a TLE string because the Name (get / set) property is longer than 24 characters.

toTleStringLine1

@Nonnull
public final String toTleStringLine1()

Returns line 1 of the TLE represented in standard NORAD format, described by CelesTrak. Line 1 contains the classification, international designator, epoch, etc. The returned line does not contain any new line or line break characters.

Returns:

Line 1 of the TLE string.

Throws:

PropertyInvalidException - The properties of this instance cannot be represented as a TLE string because a value is outside the allowed range.

toTleStringLine2

@Nonnull
public final String toTleStringLine2()

Returns line 2 of the TLE represented in standard NORAD format, described by CelesTrak. Line 2 contains the inclination, right ascension of the ascending node, eccentricity, etc. The returned line does not contain any new line or line break characters.

Returns:

Line 2 of the TLE string.

Throws:

PropertyInvalidException - The properties of this instance cannot be represented as a TLE string because a value is outside the allowed range.

toTleString

@Nonnull
public final String toTleString()

Returns a TLE string representing this TwoLineElementSet in the standard NORAD format, described by CelesTrak. The format consists of two or three lines with a new line after each. If the Name (get / set) is not null and not empty, the output contains three lines where the first is the result of TwoLineElementSet.toTleStringLine0(), the second is the result of TwoLineElementSet.toTleStringLine1(), and the third is the result of TwoLineElementSet.toTleStringLine2(). If the name is null or empty, line zero is omitted. In either case, the lines are separated by your platform's new line string, usually "\n" or "\r\n".

Returns:

The TLE string.

Throws:

PropertyInvalidException - The properties of this instance cannot be represented as a TLE string because a value is outside the allowed range or the Name (get / set) property is longer than 24 characters.

See Also:

TwoLineElementSet.toTleStringLine0(), TwoLineElementSet.toTleStringLine1(), TwoLineElementSet.toTleStringLine2()

downloadTles

@Nonnull
public static ArrayList<TwoLineElementSet> downloadTles(String satelliteIdentifier,
                                                                  @Nonnull
                                                                  JulianDate startDate,
                                                                  @Nonnull
                                                                  JulianDate stopDate)

Downloads TLE data for a given satellite from an AGI server. Multiple TLEs are returned, spanning the interval provided. This method connects via HTTPS to ftp.agi.com.

Parameters:

satelliteIdentifier - The NORAD identifier for the satellite whose TLEs are desired.

startDate - The start Julian date for the first TLE to return.

stopDate - the stop Julian date for the last TLE to return.

Returns:

List of TwoLineElementSet instances, created from the retrieved TLEs. The first TLE's epoch is just before startDate and the last TLE's epoch is just after stopDate.

Throws:

DataUnavailableException - Thrown when the data cannot be retrieved from the server.

downloadTles

@Nonnull
public static ArrayList<TwoLineElementSet> downloadTles(String satelliteIdentifier,
                                                                  @Nonnull
                                                                  JulianDate startDate,
                                                                  @Nonnull
                                                                  JulianDate stopDate,
                                                                  Proxy proxy)

Downloads TLE data for a given satellite from an AGI server. Multiple TLEs are returned, spanning the interval provided. This method connects via HTTPS to ftp.agi.com.

Parameters:

satelliteIdentifier - The NORAD identifier for the satellite whose TLEs are desired.

startDate - The start Julian date for the first TLE to return.

stopDate - the stop Julian date for the last TLE to return.

proxy - Proxy to use when connecting.

Returns:

List of TwoLineElementSet instances, created from the retrieved TLEs. The first TLE's epoch is just before startDate and the last TLE's epoch is just after stopDate.

Throws:

DataUnavailableException - Thrown when the data cannot be retrieved from the server.

tryConvertAlpha5SatelliteCatalogNumbersToIntegers

public static boolean tryConvertAlpha5SatelliteCatalogNumbersToIntegers(String alphaFiveSatelliteCatalogNumberString,
                                                                        @Nonnull
                                                                        String[] intSatelliteCatalogNumberString)

Tries to convert an Alpha-5 satellite catalog number into its corresponding integer representation.

Parameters:

alphaFiveSatelliteCatalogNumberString - The satellite catalog number represented as a 5-digit string where the first digit is alpha-numerical with only capital letters (other than I or O) and 0-9 accepted, and the final 4 digits are numerical with only 0-9 accepted for each digit. Strings with 1 to 4 digits are also accepted if all of the available digits are numerical with only 0-9 accepted for each digit. Leading and trailing whitespace will be removed automatically.

intSatelliteCatalogNumberString - On return, a string containing the integer representation of the satellite catalog number that can be up to 6 digits in length.

Returns:

true if a valid string has been entered; otherwise false.

See Also:

Alpha-5 documentation from space-track.org

tryConvertIntegerSatelliteCatalogNumbersToAlpha5

public static boolean tryConvertIntegerSatelliteCatalogNumbersToAlpha5(String intSatelliteCatalogNumberString,
                                                                       @Nonnull
                                                                       String[] alphaFiveSatelliteCatalogNumberString)

Tries to convert an integer satellite catalog number into its corresponding Alpha-5 representation.

Parameters:

intSatelliteCatalogNumberString - The satellite catalog number represented as an integer that must be positive and less than 340000 in order to be able to be converted into an Alpha-5 satellite catalog number representation. Leading and trailing whitespace will be automatically trimmed.

alphaFiveSatelliteCatalogNumberString - On return, a string of up to 5 digits where the first digit is alpha-numerical containing only capital letters (other than I or O) and 0-9, and the final 4 digits are numerical containing only 0-9 for each digit.

Returns:

true if a valid string has been entered; otherwise false.

See Also:

Alpha-5 documentation from space-track.org

getName

public final String getName()

Gets the spacecraft name

setName

public final void setName(String value)

Sets the spacecraft name

getMeanMotionDot

public final double getMeanMotionDot()

Gets the first derivative of mean motion divided by two, in revolutions per day squared.

setMeanMotionDot

public final void setMeanMotionDot(double value)

Sets the first derivative of mean motion divided by two, in revolutions per day squared.

getMeanMotionDotDot

public final double getMeanMotionDotDot()

Gets the second derivative of mean motion divided by six, in revolutions per day cubed.

Warning: This is equal to the solar radiation pressure model parameter, AGOM [m^2/kg] if the EphemerisType (get / set) is equal to 4. AGOM is the area times the coefficient of solar radiation pressure (gamma) divided by the mass of the spacecraft.

setMeanMotionDotDot

public final void setMeanMotionDotDot(double value)

Sets the second derivative of mean motion divided by six, in revolutions per day cubed.

Warning: This is equal to the solar radiation pressure model parameter, AGOM [m^2/kg] if the EphemerisType (get / set) is equal to 4. AGOM is the area times the coefficient of solar radiation pressure (gamma) divided by the mass of the spacecraft.

getRevolutionNumber

public final int getRevolutionNumber()

Gets the revolution number at epoch.

setRevolutionNumber

public final void setRevolutionNumber(int value)

Sets the revolution number at epoch.

getSatelliteNumber

public final String getSatelliteNumber()

Gets the satellite number.

setSatelliteNumber

public final void setSatelliteNumber(String value)

Sets the satellite number.

getEphemerisType

public final int getEphemerisType()

Gets the ephemeris type. Ephemeris Type 0 is the correct type for Sgp4Propagator. Ephemeris type 4 is not supported by Sgp4Propagator, and it will throw an argument exception if a TwoLineElementSet has ephemeris type 4.

setEphemerisType

public final void setEphemerisType(int value)

Sets the ephemeris type. Ephemeris Type 0 is the correct type for Sgp4Propagator. Ephemeris type 4 is not supported by Sgp4Propagator, and it will throw an argument exception if a TwoLineElementSet has ephemeris type 4.

getClassification

public final String getClassification()

Gets the classification.

setClassification

public final void setClassification(String value)

Sets the classification.

getInternationalDesignator

public final String getInternationalDesignator()

Gets the international designator

setInternationalDesignator

public final void setInternationalDesignator(String value)

Sets the international designator

getChecksumLine1

public final int getChecksumLine1()

Gets the checksum for line 1.

setChecksumLine1

public final void setChecksumLine1(int value)

Sets the checksum for line 1.

getChecksumLine2

public final int getChecksumLine2()

Gets the checksum for line 2.

setChecksumLine2

public final void setChecksumLine2(int value)

Sets the checksum for line 2.

getElementNumber

public final int getElementNumber()

Gets the element number

setElementNumber

public final void setElementNumber(int value)

Sets the element number

verifyChecksum

public static boolean verifyChecksum(String line)

Verifies the checksum of the specified TLE line.

Parameters:

line - The TLE line to verify.

Returns:

true if the checksum matches the rest of the line; otherwise false.