ADMParser.java

  1. /* Copyright 2002-2020 CS GROUP
  2.  * Licensed to CS GROUP (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.files.ccsds;

  19. import java.io.FileInputStream;
  20. import java.io.IOException;
  21. import java.io.InputStream;
  22. import java.util.List;
  23. import java.util.regex.Matcher;
  24. import java.util.regex.Pattern;

  26. import org.hipparchus.complex.Quaternion;
  27. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  28. import org.hipparchus.util.FastMath;
  29. import org.orekit.bodies.CelestialBodies;
  30. import org.orekit.data.DataContext;
  31. import org.orekit.errors.OrekitException;
  32. import org.orekit.errors.OrekitMessages;
  33. import org.orekit.time.AbsoluteDate;
  34. import org.orekit.utils.IERSConventions;

  36. /**
  37.  * Base class for all CCSDS Attitude Data Message parsers.
  38.  *
  39.  * <p> This base class is immutable, and hence thread safe. When parts must be
  40.  * changed, such as reference date for Mission Elapsed Time or Mission Relative
  41.  * Time time systems, or the gravitational coefficient or the IERS conventions,
  42.  * the various {@code withXxx} methods must be called, which create a new
  43.  * immutable instance with the new parameters. This is a combination of the <a
  44.  * href="https://en.wikipedia.org/wiki/Builder_pattern">builder design
  45.  * pattern</a> and a <a href="http://en.wikipedia.org/wiki/Fluent_interface">fluent
  46.  * interface</a>.
  47.  *
  48.  * @author Bryan Cazabonne
  49.  * @since 10.2
  50.  */
  51. public abstract class ADMParser {

  53.     /** Pattern for international designator. */
  54.     private static final Pattern INTERNATIONAL_DESIGNATOR = Pattern.compile("(\\p{Digit}{4})-(\\p{Digit}{3})(\\p{Upper}{1,3})");

  56.     /** Reference date for Mission Elapsed Time or Mission Relative Time time systems. */
  57.     private final AbsoluteDate missionReferenceDate;

  59.     /** Gravitational coefficient. */
  60.     private final  double mu;

  62.     /** IERS Conventions. */
  63.     private final  IERSConventions conventions;

  65.     /** Indicator for simple or accurate EOP interpolation. */
  66.     private final  boolean simpleEOP;

  68.     /** Data context used for obtain frames and time scales. */
  69.     private final DataContext dataContext;

  71.     /** Launch Year. */
  72.     private int launchYear;

  74.     /** Launch number. */
  75.     private int launchNumber;

  77.     /** Piece of launch (from "A" to "ZZZ"). */
  78.     private String launchPiece;

  80.     /** Complete constructor.
  81.      * @param missionReferenceDate reference date for Mission Elapsed Time or Mission Relative Time time systems
  82.      * @param mu gravitational coefficient
  83.      * @param conventions IERS Conventions
  84.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  85.      * @param launchYear launch year for TLEs
  86.      * @param launchNumber launch number for TLEs
  87.      * @param launchPiece piece of launch (from "A" to "ZZZ") for TLEs
  88.      * @param dataContext used to retrieve frames and time scales.
  89.      */
  90.     protected ADMParser(final AbsoluteDate missionReferenceDate, final double mu,
  91.                         final IERSConventions conventions, final boolean simpleEOP,
  92.                         final int launchYear, final int launchNumber,
  93.                         final String launchPiece,
  94.                         final DataContext dataContext) {
  95.         this.missionReferenceDate = missionReferenceDate;
  96.         this.mu                   = mu;
  97.         this.conventions          = conventions;
  98.         this.simpleEOP            = simpleEOP;
  99.         this.launchYear           = launchYear;
  100.         this.launchNumber         = launchNumber;
  101.         this.launchPiece          = launchPiece;
  102.         this.dataContext          = dataContext;
  103.     }

  105.     /**
  106.      * Set initial date.
  107.      * @param newMissionReferenceDate mission reference date to use while parsing
  108.      * @return a new instance, with mission reference date replaced
  109.      * @see #getMissionReferenceDate()
  110.      */
  111.     public abstract ADMParser withMissionReferenceDate(AbsoluteDate newMissionReferenceDate);

  113.     /**
  114.      * Get initial date.
  115.      * @return mission reference date to use while parsing
  116.      * @see #withMissionReferenceDate(AbsoluteDate)
  117.      */
  118.     public AbsoluteDate getMissionReferenceDate() {
  119.         return missionReferenceDate;
  120.     }

  122.     /**
  123.      * Set gravitational coefficient.
  124.      * @param newMu gravitational coefficient to use while parsing
  125.      * @return a new instance, with gravitational coefficient date replaced
  126.      * @see #getMu()
  127.      */
  128.     public abstract ADMParser withMu(double newMu);

  130.     /**
  131.      * Get gravitational coefficient.
  132.      * @return gravitational coefficient to use while parsing
  133.      * @see #withMu(double)
  134.      */
  135.     public double getMu() {
  136.         return mu;
  137.     }

  139.     /**
  140.      * Set IERS conventions.
  141.      * @param newConventions IERS conventions to use while parsing
  142.      * @return a new instance, with IERS conventions replaced
  143.      * @see #getConventions()
  144.      */
  145.     public abstract ADMParser withConventions(IERSConventions newConventions);

  147.     /**
  148.      * Get IERS conventions.
  149.      * @return IERS conventions to use while parsing
  150.      * @see #withConventions(IERSConventions)
  151.      */
  152.     public IERSConventions getConventions() {
  153.         return conventions;
  154.     }

  156.     /**
  157.      * Set EOP interpolation method.
  158.      * @param newSimpleEOP if true, tidal effects are ignored when interpolating EOP
  159.      * @return a new instance, with EOP interpolation method replaced
  160.      * @see #isSimpleEOP()
  161.      */
  162.     public abstract ADMParser withSimpleEOP(boolean newSimpleEOP);

  164.     /**
  165.      * Get EOP interpolation method.
  166.      * @return true if tidal effects are ignored when interpolating EOP
  167.      * @see #withSimpleEOP(boolean)
  168.      */
  169.     public boolean isSimpleEOP() {
  170.         return simpleEOP;
  171.     }

  173.     /**
  174.      * Set international designator.
  175.      * <p>
  176.      * This method may be used to ensure the launch year number and pieces are
  177.      * correctly set if they are not present in the CCSDS file header in the
  178.      * OBJECT_ID in the form YYYY-NNNP{PP}. If they are already in the header,
  179.      * they will be parsed automatically regardless of this method being called
  180.      * or not (i.e. header information override information set here).
  181.      * </p>
  182.      * @param newLaunchYear launch year
  183.      * @param newLaunchNumber launch number
  184.      * @param newLaunchPiece piece of launch (from "A" to "ZZZ")
  185.      * @return a new instance, with TLE settings replaced
  186.      */
  187.     public abstract ADMParser withInternationalDesignator(int newLaunchYear,
  188.                                                           int newLaunchNumber,
  189.                                                           String newLaunchPiece);

  191.     /**
  192.      * Get the launch year.
  193.      * @return launch year
  194.      */
  195.     public int getLaunchYear() {
  196.         return launchYear;
  197.     }

  199.     /**
  200.      * Get the launch number.
  201.      * @return launch number
  202.      */
  203.     public int getLaunchNumber() {
  204.         return launchNumber;
  205.     }

  207.     /**
  208.      * Get the piece of launch.
  209.      * @return piece of launch
  210.      */
  211.     public String getLaunchPiece() {
  212.         return launchPiece;
  213.     }

  215.     /**
  216.      * Get the data context used for getting frames, time scales, and celestial bodies.
  217.      * @return the data context.
  218.      */
  219.     public DataContext getDataContext() {
  220.         return dataContext;
  221.     }

  223.     /**
  224.      * Set the data context.
  225.      * @param newDataContext used for frames, time scales, and celestial bodies.
  226.      * @return a new instance with the data context replaced.
  227.      */
  228.     public abstract ADMParser withDataContext(DataContext newDataContext);

  230.     /**
  231.      * Parse a CCSDS Attitude Data Message.
  232.      * @param fileName name of the file containing the message
  233.      * @return parsed ADM file
  234.      */
  235.     public ADMFile parse(final String fileName) {
  236.         try (InputStream stream = new FileInputStream(fileName)) {
  237.             return parse(stream, fileName);
  238.         } catch (IOException e) {
  239.             throw new OrekitException(OrekitMessages.UNABLE_TO_FIND_FILE, fileName);
  240.         }
  241.     }

  243.     /**
  244.      * Parse a CCSDS Attitude Data Message.
  245.      * @param stream stream containing message
  246.      * @return parsed ADM file
  247.      */
  248.     public ADMFile parse(final InputStream stream) {
  249.         return parse(stream, "<unknown>");
  250.     }

  252.     /**
  253.      * Parse a CCSDS Attitude Data Message.
  254.      * @param stream stream containing message
  255.      * @param fileName name of the file containing the message (for error messages)
  256.      * @return parsed ADM file
  257.      */
  258.     public abstract ADMFile parse(InputStream stream, String fileName);

  260.     /**
  261.      * Parse a comment line.
  262.      * @param keyValue key=value pair containing the comment
  263.      * @param comment placeholder where the current comment line should be added
  264.      * @return true if the line was a comment line and was parsed
  265.      */
  266.     protected boolean parseComment(final KeyValue keyValue, final List<String> comment) {
  267.         if (keyValue.getKeyword() == Keyword.COMMENT) {
  268.             comment.add(keyValue.getValue());
  269.             return true;
  270.         } else {
  271.             return false;
  272.         }
  273.     }

  275.     /**
  276.      * Parse an entry from the header.
  277.      * @param keyValue key = value pair
  278.      * @param admFile instance to update with parsed entry
  279.      * @param comment previous comment lines, will be emptied if used by the keyword
  280.      * @return true if the keyword was a header keyword and has been parsed
  281.      */
  282.     protected boolean parseHeaderEntry(final KeyValue keyValue,
  283.                                        final ADMFile admFile, final List<String> comment) {
  284.         switch (keyValue.getKeyword()) {

  286.             case CREATION_DATE:
  287.                 if (!comment.isEmpty()) {
  288.                     admFile.setHeaderComment(comment);
  289.                     comment.clear();
  290.                 }
  291.                 admFile.setCreationDate(new AbsoluteDate(
  292.                         keyValue.getValue(),
  293.                         dataContext.getTimeScales().getUTC()));
  294.                 return true;

  296.             case ORIGINATOR:
  297.                 admFile.setOriginator(keyValue.getValue());
  298.                 return true;

  300.             default:
  301.                 return false;

  303.         }

  305.     }

  307.     /**
  308.      * Parse a meta-data key = value entry.
  309.      * @param keyValue key = value pair
  310.      * @param metaData instance to update with parsed entry
  311.      * @param comment previous comment lines, will be emptied if used by the keyword
  312.      * @return true if the keyword was a meta-data keyword and has been parsed
  313.      */
  314.     protected boolean parseMetaDataEntry(final KeyValue keyValue,
  315.                                          final ADMMetaData metaData, final List<String> comment) {
  316.         switch (keyValue.getKeyword()) {
  317.             case OBJECT_NAME:
  318.                 if (!comment.isEmpty()) {
  319.                     metaData.setComment(comment);
  320.                     comment.clear();
  321.                 }
  322.                 metaData.setObjectName(keyValue.getValue());
  323.                 return true;

  325.             case OBJECT_ID: {
  326.                 metaData.setObjectID(keyValue.getValue());
  327.                 final Matcher matcher = INTERNATIONAL_DESIGNATOR.matcher(keyValue.getValue());
  328.                 if (matcher.matches()) {
  329.                     metaData.setLaunchYear(Integer.parseInt(matcher.group(1)));
  330.                     metaData.setLaunchNumber(Integer.parseInt(matcher.group(2)));
  331.                     metaData.setLaunchPiece(matcher.group(3));
  332.                 }
  333.                 return true;
  334.             }

  336.             case CENTER_NAME:
  337.                 metaData.setCenterName(keyValue.getValue());
  338.                 final String canonicalValue;
  339.                 if (keyValue.getValue().equals("SOLAR SYSTEM BARYCENTER") || keyValue.getValue().equals("SSB")) {
  340.                     canonicalValue = "SOLAR_SYSTEM_BARYCENTER";
  341.                 } else if (keyValue.getValue().equals("EARTH MOON BARYCENTER") || keyValue.getValue().equals("EARTH-MOON BARYCENTER") ||
  342.                         keyValue.getValue().equals("EARTH BARYCENTER") || keyValue.getValue().equals("EMB")) {
  343.                     canonicalValue = "EARTH_MOON";
  344.                 } else {
  345.                     canonicalValue = keyValue.getValue();
  346.                 }
  347.                 for (final CenterName c : CenterName.values()) {
  348.                     if (c.name().equals(canonicalValue)) {
  349.                         metaData.setHasCreatableBody(true);
  350.                         final CelestialBodies celestialBodies =
  351.                                 getDataContext().getCelestialBodies();
  352.                         metaData.setCenterBody(c.getCelestialBody(celestialBodies));
  353.                         metaData.getADMFile().setMu( c.getCelestialBody(celestialBodies).getGM());
  354.                     }
  355.                 }
  356.                 return true;

  358.             case TIME_SYSTEM:
  359.                 if (!CcsdsTimeScale.contains(keyValue.getValue())) {
  360.                     throw new OrekitException(
  361.                             OrekitMessages.CCSDS_TIME_SYSTEM_NOT_IMPLEMENTED,
  362.                             keyValue.getValue());
  363.                 }
  364.                 final CcsdsTimeScale timeSystem =
  365.                         CcsdsTimeScale.valueOf(keyValue.getValue());
  366.                 metaData.setTimeSystem(timeSystem);
  367.                 return true;

  369.             default:
  370.                 return false;
  371.         }
  372.     }

  374.     /**
  375.      * Parse a general state data key = value entry.
  376.      * @param keyValue key = value pair
  377.      * @param general instance to update with parsed entry
  378.      * @param comment previous comment lines, will be emptied if used by the keyword
  379.      * @return true if the keyword was a meta-data keyword and has been parsed
  380.      */
  381.     protected boolean parseGeneralStateDataEntry(final KeyValue keyValue,
  382.                                                  final APMFile general, final List<String> comment) {
  383.         switch (keyValue.getKeyword()) {

  385.             case EPOCH:
  386.                 general.setEpochComment(comment);
  387.                 comment.clear();
  388.                 general.setEpoch(parseDate(keyValue.getValue(), general.getMetaData().getTimeSystem()));
  389.                 return true;

  391.             case QC_DOT:
  392.                 general.setQuaternionDot(new Quaternion(keyValue.getDoubleValue(),
  393.                                                         general.getQuaternionDot().getQ1(),
  394.                                                         general.getQuaternionDot().getQ2(),
  395.                                                         general.getQuaternionDot().getQ3()));
  396.                 return true;

  398.             case Q1_DOT:
  399.                 general.setQuaternionDot(new Quaternion(general.getQuaternionDot().getQ0(),
  400.                                                         keyValue.getDoubleValue(),
  401.                                                         general.getQuaternionDot().getQ2(),
  402.                                                         general.getQuaternionDot().getQ3()));
  403.                 return true;

  405.             case Q2_DOT:
  406.                 general.setQuaternionDot(new Quaternion(general.getQuaternionDot().getQ0(),
  407.                                                         general.getQuaternionDot().getQ1(),
  408.                                                         keyValue.getDoubleValue(),
  409.                                                         general.getQuaternionDot().getQ3()));
  410.                 return true;

  412.             case Q3_DOT:
  413.                 general.setQuaternionDot(new Quaternion(general.getQuaternionDot().getQ0(),
  414.                                                         general.getQuaternionDot().getQ1(),
  415.                                                         general.getQuaternionDot().getQ2(),
  416.                                                         keyValue.getDoubleValue()));
  417.                 return true;

  419.             case EULER_FRAME_A:
  420.                 general.setEulerComment(comment);
  421.                 comment.clear();
  422.                 general.setEulerFrameAString(keyValue.getValue());
  423.                 return true;

  425.             case EULER_FRAME_B:
  426.                 general.setEulerFrameBString(keyValue.getValue());
  427.                 return true;

  429.             case EULER_DIR:
  430.                 general.setEulerDirection(keyValue.getValue());
  431.                 return true;

  433.             case EULER_ROT_SEQ:
  434.                 general.setEulerRotSeq(keyValue.getValue());
  435.                 return true;

  437.             case RATE_FRAME:
  438.                 general.setRateFrameString(keyValue.getValue());
  439.                 return true;

  441.             case X_ANGLE:
  442.                 general.setRotationAngles(new Vector3D(toRadians(keyValue),
  443.                                                        general.getRotationAngles().getY(),
  444.                                                        general.getRotationAngles().getZ()));
  445.                 return true;

  447.             case Y_ANGLE:
  448.                 general.setRotationAngles(new Vector3D(general.getRotationAngles().getX(),
  449.                                                        toRadians(keyValue),
  450.                                                        general.getRotationAngles().getZ()));
  451.                 return true;

  453.             case Z_ANGLE:
  454.                 general.setRotationAngles(new Vector3D(general.getRotationAngles().getX(),
  455.                                                        general.getRotationAngles().getY(),
  456.                                                        toRadians(keyValue)));
  457.                 return true;

  459.             case X_RATE:
  460.                 general.setRotationRates(new Vector3D(toRadians(keyValue),
  461.                                                       general.getRotationRates().getY(),
  462.                                                       general.getRotationRates().getZ()));
  463.                 return true;

  465.             case Y_RATE:
  466.                 general.setRotationRates(new Vector3D(general.getRotationRates().getX(),
  467.                                                       toRadians(keyValue),
  468.                                                       general.getRotationRates().getZ()));
  469.                 return true;

  471.             case Z_RATE:
  472.                 general.setRotationRates(new Vector3D(general.getRotationRates().getX(),
  473.                                                       general.getRotationRates().getY(),
  474.                                                       toRadians(keyValue)));
  475.                 return true;

  477.             case SPIN_FRAME_A:
  478.                 general.setSpinComment(comment);
  479.                 comment.clear();
  480.                 general.setSpinFrameAString(keyValue.getValue());
  481.                 return true;

  483.             case SPIN_FRAME_B:
  484.                 general.setSpinFrameBString(keyValue.getValue());
  485.                 return true;

  487.             case SPIN_DIR:
  488.                 general.setSpinDirection(keyValue.getValue());
  489.                 return true;

  491.             case SPIN_ALPHA:
  492.                 general.setSpinAlpha(toRadians(keyValue));
  493.                 return true;

  495.             case SPIN_DELTA:
  496.                 general.setSpinDelta(toRadians(keyValue));
  497.                 return true;

  499.             case SPIN_ANGLE:
  500.                 general.setSpinAngle(toRadians(keyValue));
  501.                 return true;

  503.             case SPIN_ANGLE_VEL:
  504.                 general.setSpinAngleVel(toRadians(keyValue));
  505.                 return true;

  507.             case NUTATION:
  508.                 general.setNutation(toRadians(keyValue));
  509.                 return true;

  511.             case NUTATION_PER:
  512.                 general.setNutationPeriod(keyValue.getDoubleValue());
  513.                 return true;

  515.             case NUTATION_PHASE:
  516.                 general.setNutationPhase(toRadians(keyValue));
  517.                 return true;

  519.             case INERTIA_REF_FRAME:
  520.                 general.setSpacecraftComment(comment);
  521.                 comment.clear();
  522.                 general.setInertiaRefFrameString(keyValue.getValue());
  523.                 return true;

  525.             case I11:
  526.                 general.setI11(keyValue.getDoubleValue());
  527.                 return true;

  529.             case I22:
  530.                 general.setI22(keyValue.getDoubleValue());
  531.                 return true;

  533.             case I33:
  534.                 general.setI33(keyValue.getDoubleValue());
  535.                 return true;

  537.             case I12:
  538.                 general.setI12(keyValue.getDoubleValue());
  539.                 return true;

  541.             case I13:
  542.                 general.setI13(keyValue.getDoubleValue());
  543.                 return true;

  545.             case I23:
  546.                 general.setI23(keyValue.getDoubleValue());
  547.                 return true;

  549.             default:
  550.                 return false;

  552.         }

  554.     }

  556.     /**
  557.      * Parse a date.
  558.      * @param date date to parse, as the value of a CCSDS key=value line
  559.      * @param timeSystem time system to use
  560.      * @return parsed date
  561.      */
  562.     protected AbsoluteDate parseDate(final String date, final CcsdsTimeScale timeSystem) {
  563.         return timeSystem.parseDate(date, conventions, missionReferenceDate,
  564.                 getDataContext().getTimeScales());
  565.     }

  567.     /**
  568.      * Convert a {@link KeyValue} in degrees to a real value in randians.
  569.      * @param keyValue key value
  570.      * @return the value in radians
  571.      */
  572.     protected double toRadians(final KeyValue keyValue) {
  573.         return FastMath.toRadians(keyValue.getDoubleValue());
  574.     }

  576. }
Created with JaCoCo 0.8.6.202009150832