agi.foundation.propagators

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

Class CelestrakGeneralPerturbationElements

java.lang.Object

agi.foundation.propagators.Sgp4Elements

agi.foundation.propagators.CelestrakGeneralPerturbationElements

All Implemented Interfaces:

ICloneWithContext

public class CelestrakGeneralPerturbationElements
extends Sgp4Elements

Celestrak general perturbation (GP) orbital elements.

The following example shows how to create a Sgp4Propagator from a CSV-format Celestrak General Perturbation elements file.

// Header for CELESTRAK General Perturbation elements CSV file.
final String csvGpHeader =
        "OBJECT_NAME,OBJECT_ID,EPOCH,MEAN_MOTION,ECCENTRICITY,INCLINATION," +
        "RA_OF_ASC_NODE,ARG_OF_PERICENTER,MEAN_ANOMALY,EPHEMERIS_TYPE," +
        "CLASSIFICATION_TYPE,NORAD_CAT_ID,ELEMENT_SET_NO,REV_AT_EPOCH,BSTAR," +
        "MEAN_MOTION_DOT,MEAN_MOTION_DDOT";
final String csvGpRowOne =
        "UNKNOWN,1987-068,2020-06-23T04:36:00.383904,14.29842842,.0066057,82.6660," +
        "87.5455,38.3103,322.2748,0,U,81409,999,34254,.46387E-3,1.238E-5,0";

StringBuilder builder = new StringBuilder();
builder.append(csvGpHeader).append(System.lineSeparator());
builder.append(csvGpRowOne).append(System.lineSeparator());

Sgp4Propagator propagator;
try (BufferedReader reader = new BufferedReader(new StringReader(builder.toString()))) {
    ArrayList<CelestrakGeneralPerturbationElements> csvGpList = CelestrakGeneralPerturbationElements.readFromCsvFile(reader);
    CelestrakGeneralPerturbationElements csvGp = csvGpList.get(0);
    propagator = new Sgp4Propagator(csvGp);
}

Warning: If the EphemerisType (get / set) is 4, Sgp4Propagator will throw an exception if the Celestrak GP elements is input.

Constructor Summary

Constructors

Constructor and Description
CelestrakGeneralPerturbationElements() Initializes a new instance.
CelestrakGeneralPerturbationElements(CelestrakGeneralPerturbationElements existingInstance) Initializes a new instance as a copy of an existing instance.
CelestrakGeneralPerturbationElements(Sgp4Elements elements, String name, String satelliteNumber, String classification, String internationalDesignator, double meanMotionDot, double meanMotionDotDot, int ephemerisType, int elementNumber, int revolutions) Initializes a new instance from a set of Sgp4Elements and additional meta-data contained in a Celestrak General Perturbation file.

Method Summary

Modifier and Type	Method and Description
Object	clone(CopyContext context) Clones this object using the specified context.
String	getClassification() Gets the classification.
int	getElementNumber() Gets the element number.
int	getEphemerisType() Gets the ephemeris type.
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.
int	getRevolutionNumber() Gets the revolution number at epoch.
String	getSatelliteNumber() Gets the satellite number.
static ArrayList<CelestrakGeneralPerturbationElements>	readFromCsvFile(BufferedReader reader) Reads the Celestrak General Perturbation elements in from a file (most likely a .csv).
static ArrayList<CelestrakGeneralPerturbationElements>	readFromCsvFile(String filename) Reads the Celestrak General Perturbation elements in from a file (most likely a .csv).
void	setClassification(String value) Sets the classification.
void	setElementNumber(int value) Sets the element number.
void	setEphemerisType(int value) Sets the ephemeris type.
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	setRevolutionNumber(int value) Sets the revolution number at epoch.
void	setSatelliteNumber(String value) Sets the satellite number.

Methods inherited from class agi.foundation.propagators.Sgp4Elements

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

Methods inherited from class java.lang.Object

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

Constructor Detail

CelestrakGeneralPerturbationElements

public CelestrakGeneralPerturbationElements()

Initializes a new instance.

CelestrakGeneralPerturbationElements

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

Initializes a new instance from a set of Sgp4Elements and additional meta-data contained in a Celestrak General Perturbation file.

Parameters:

elements - The elements specifying the essential orbit ephemeris data.

name - The name of the satellite.

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 in revolutions per day.

meanMotionDotDot - The second time derivative of the mean motion at epoch in revolutions per day squared.

ephemerisType - The ephemeris type of the elements. 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 CelestrakGeneralPerturbationElements has ephemeris type 4.

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.

CelestrakGeneralPerturbationElements

public CelestrakGeneralPerturbationElements(@Nonnull
                                            CelestrakGeneralPerturbationElements 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.

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.

setMeanMotionDotDot

public final void setMeanMotionDotDot(double value)

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

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 CelestrakGeneralPerturbationElements 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 CelestrakGeneralPerturbationElements 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.

getElementNumber

public final int getElementNumber()

Gets the element number.

setElementNumber

public final void setElementNumber(int value)

Sets the element number.

readFromCsvFile

@Nonnull
public static ArrayList<CelestrakGeneralPerturbationElements> readFromCsvFile(@Nonnull
                                                                                        String filename)

Reads the Celestrak General Perturbation elements in from a file (most likely a .csv).

The Celestrak General Perturbation CSV format includes a header row before the actual CSV data. The reader will first parse the first row. The first row is considered a valid header row if it contains all of the obligatory CCSDS Orbit Mean-Elements Message (OMM) Data keywords and all of the TLE Related Parameters (other than COMMENT). MEAN_MOTION must be used rather than the SEMI_MAJOR_AXIS. These keywords can be in any order, but all of them must be included as comma-separated entries in the first row for the header to be valid. The second and subsequent rows must have entries in formats consistent with the header keywords in the first row. See Table 4-3 of the document titled "Orbit Data Messages" from the CCSDS website.

Parameters:

filename - Name of the CSV file from which to read.

Returns:

A list of CelestrakGeneralPerturbationElements.

Throws:

ArgumentNullException - Thrown when filename is null.

readFromCsvFile

@Nonnull
public static ArrayList<CelestrakGeneralPerturbationElements> readFromCsvFile(@Nonnull
                                                                                        BufferedReader reader)

Reads the Celestrak General Perturbation elements in from a file (most likely a .csv).

The Celestrak General Perturbation CSV format includes a header row before the actual CSV data. The reader will first parse the first row. The first row is considered a valid header row if it contains all of the obligatory CCSDS Orbit Mean-Elements Message (OMM) Data keywords and all of the TLE Related Parameters (other than COMMENT). MEAN_MOTION must be used rather than the SEMI_MAJOR_AXIS. These keywords can be in any order, but all of them must be included as comma-separated entries in the first row for the header to be valid. The second and subsequent rows must have entries in formats consistent with the header keywords in the first row. See Table 4-3 of the document titled "Orbit Data Messages" from the CCSDS website.

Parameters:

reader - BufferedReader for the .csv file to read.

Returns:

A list of CelestrakGeneralPerturbationElements.

Throws:

ArgumentNullException - Thrown when reader is null.