StreamingAemWriter.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.IOException;
  20. import java.text.DecimalFormat;
  21. import java.text.DecimalFormatSymbols;
  22. import java.time.ZoneOffset;
  23. import java.time.ZonedDateTime;
  24. import java.time.format.DateTimeFormatter;
  25. import java.util.Date;
  26. import java.util.LinkedHashMap;
  27. import java.util.Locale;
  28. import java.util.Map;

  30. import org.hipparchus.exception.LocalizedCoreFormats;
  31. import org.hipparchus.geometry.euclidean.threed.RotationOrder;
  32. import org.orekit.errors.OrekitException;
  33. import org.orekit.files.ccsds.AEMParser.AEMRotationOrder;
  34. import org.orekit.propagation.SpacecraftState;
  35. import org.orekit.propagation.sampling.OrekitFixedStepHandler;
  36. import org.orekit.time.AbsoluteDate;
  37. import org.orekit.time.DateTimeComponents;
  38. import org.orekit.time.TimeComponents;
  39. import org.orekit.time.TimeScale;
  40. import org.orekit.utils.TimeStampedAngularCoordinates;

  42. /**
  43.  * A writer for AEM files.
  44.  *
  45.  * <p> Each instance corresponds to a single AEM file.
  46.  *
  47.  * <h3> Metadata </h3>
  48.  *
  49.  * <p> The AEM metadata used by this writer is described in the following table. Many
  50.  * metadata items are optional or have default values so they do not need to be specified.
  51.  * At a minimum the user must supply those values that are required and for which no
  52.  * default exits: {@link Keyword#OBJECT_NAME}, and {@link Keyword#OBJECT_ID}. The usage
  53.  * column in the table indicates where the metadata item is used, either in the AEM header
  54.  * or in the metadata section at the start of an AEM attitude segment.
  55.  *
  56.  * <p> The AEM metadata for the whole AEM file is set in the {@link
  57.  * #StreamingAemWriter(Appendable, TimeScale, Map) constructor}.
  58.  *
  59.  * <table summary="AEM metada">
  60.  *     <thead>
  61.  *         <tr>
  62.  *             <th>Keyword
  63.  *             <th>Usage
  64.  *             <th>Obligatory
  65.  *             <th>Default
  66.  *             <th>Reference
  67.  *    </thead>
  68.  *    <tbody>
  69.  *        <tr>
  70.  *            <td>{@link Keyword#CCSDS_AEM_VERS}
  71.  *            <td>Header
  72.  *            <td>Yes
  73.  *            <td>{@link #CCSDS_AEM_VERS}
  74.  *            <td>Table 4-2
  75.  *        <tr>
  76.  *            <td>{@link Keyword#COMMENT}
  77.  *            <td>Header
  78.  *            <td>No
  79.  *            <td>
  80.  *            <td>Table 4-2
  81.  *        <tr>
  82.  *            <td>{@link Keyword#CREATION_DATE}
  83.  *            <td>Header
  84.  *            <td>Yes
  85.  *            <td>{@link Date#Date() Now}
  86.  *            <td>Table 4-2
  87.  *        <tr>
  88.  *            <td>{@link Keyword#ORIGINATOR}
  89.  *            <td>Header
  90.  *            <td>Yes
  91.  *            <td>{@link #DEFAULT_ORIGINATOR}
  92.  *            <td>Table 4-2
  93.  *        <tr>
  94.  *            <td>{@link Keyword#OBJECT_NAME}
  95.  *            <td>Segment
  96.  *            <td>Yes
  97.  *            <td>
  98.  *            <td>Table 4-3
  99.  *        <tr>
  100.  *            <td>{@link Keyword#OBJECT_ID}
  101.  *            <td>Segment
  102.  *            <td>Yes
  103.  *            <td>
  104.  *            <td>Table 4-3
  105.  *        <tr>
  106.  *            <td>{@link Keyword#CENTER_NAME}
  107.  *            <td>Segment
  108.  *            <td>No
  109.  *            <td>
  110.  *            <td>Table 4-3
  111.  *        <tr>
  112.  *            <td>{@link Keyword#REF_FRAME_A}
  113.  *            <td>Segment
  114.  *            <td>Yes
  115.  *            <td>
  116.  *            <td>Table 4-3
  117.  *        <tr>
  118.  *            <td>{@link Keyword#REF_FRAME_B}
  119.  *            <td>Segment
  120.  *            <td>Yes
  121.  *            <td>
  122.  *            <td>Table 4-3
  123.  *        <tr>
  124.  *            <td>{@link Keyword#ATTITUDE_DIR}
  125.  *            <td>Segment
  126.  *            <td>Yes
  127.  *            <td>
  128.  *            <td>Table 4-3
  129.  *        <tr>
  130.  *            <td>{@link Keyword#TIME_SYSTEM}
  131.  *            <td>Segment
  132.  *            <td>Yes
  133.  *            <td>
  134.  *            <td>Table 4-3, Annex A
  135.  *        <tr>
  136.  *            <td>{@link Keyword#START_TIME}
  137.  *            <td>Segment
  138.  *            <td>Yes
  139.  *            <td>
  140.  *            <td>Table 4-3
  141.  *        <tr>
  142.  *            <td>{@link Keyword#USEABLE_START_TIME}
  143.  *            <td>Segment
  144.  *            <td>No
  145.  *            <td>
  146.  *            <td>Table 4-3
  147.  *        <tr>
  148.  *            <td>{@link Keyword#STOP_TIME}
  149.  *            <td>Segment
  150.  *            <td>Yes
  151.  *            <td>
  152.  *            <td>Table 4-3
  153.  *        <tr>
  154.  *            <td>{@link Keyword#USEABLE_STOP_TIME}
  155.  *            <td>Segment
  156.  *            <td>No
  157.  *            <td>
  158.  *            <td>Table 4-3
  159.  *        <tr>
  160.  *            <td>{@link Keyword#ATTITUDE_TYPE}
  161.  *            <td>Segment
  162.  *            <td>Yes
  163.  *            <td>
  164.  *            <td>Table 4-3, 4-4
  165.  *        <tr>
  166.  *            <td>{@link Keyword#QUATERNION_TYPE}
  167.  *            <td>Segment
  168.  *            <td>No
  169.  *            <td>
  170.  *            <td>Table 4-3, 4-4
  171.  *        <tr>
  172.  *            <td>{@link Keyword#EULER_ROT_SEQ}
  173.  *            <td>Segment
  174.  *            <td>No
  175.  *            <td>
  176.  *            <td>Table 4-3
  177.  *        <tr>
  178.  *            <td>{@link Keyword#RATE_FRAME}
  179.  *            <td>Segment
  180.  *            <td>No
  181.  *            <td>
  182.  *            <td>Table 4-3
  183.  *        <tr>
  184.  *            <td>{@link Keyword#INTERPOLATION_METHOD}
  185.  *            <td>Segment
  186.  *            <td>No
  187.  *            <td>
  188.  *            <td>Table 4-3
  189.  *        <tr>
  190.  *            <td>{@link Keyword#INTERPOLATION_DEGREE}
  191.  *            <td>Segment
  192.  *            <td>No
  193.  *            <td>
  194.  *            <td>Table 4-3
  195.  *    </tbody>
  196.  *</table>
  197.  *
  198.  * <p> The {@link Keyword#TIME_SYSTEM} must be constant for the whole file and is used
  199.  * to interpret all dates except {@link Keyword#CREATION_DATE}. The guessing algorithm
  200.  * is not guaranteed to work so it is recommended to provide values for {@link
  201.  * Keyword#CENTER_NAME} and {@link Keyword#TIME_SYSTEM} to avoid any bugs associated with
  202.  * incorrect guesses.
  203.  *
  204.  * <p> Standardized values for {@link Keyword#TIME_SYSTEM} are GMST, GPS, MET, MRT, SCLK,
  205.  * TAI, TCB, TDB, TT, UT1, and UTC. Standardized values for reference frames
  206.  * are EME2000, GTOD, ICRF, ITRF2000, ITRF-93, ITRF-97, LVLH, RTN, QSW, TOD, TNW, NTW and RSW.
  207.  * Additionally ITRF followed by a four digit year may be used.
  208.  *
  209.  * @author Bryan Cazabonne
  210.  * @see <a href="https://public.ccsds.org/Pubs/504x0b1c1.pdf">CCSDS 504.0-B-1 Attitude Data Messages</a>
  211.  * @see AEMWriter
  212.  * @since 10.2
  213.  */
  214. public class StreamingAemWriter {

  216.     /** Version number implemented. **/
  217.     public static final String CCSDS_AEM_VERS = "1.0";

  219.     /** Default value for {@link Keyword#ORIGINATOR}. */
  220.     public static final String DEFAULT_ORIGINATOR = "OREKIT";

  222.     /** New line separator for output file. See 5.4.5. */
  223.     private static final String NEW_LINE = "\n";

  225.     /** Standardized locale to use, to ensure files can be exchanged without internationalization issues. */
  226.     private static final Locale STANDARDIZED_LOCALE = Locale.US;

  228.     /** String format used for all key/value pair lines. **/
  229.     private static final String KV_FORMAT = "%s = %s%n";

  231.     /** Output stream. */
  232.     private final Appendable writer;

  234.     /** Metadata for this AEM file. */
  235.     private final Map<Keyword, String> metadata;

  237.     /** Time scale for all dates except {@link Keyword#CREATION_DATE}. */
  238.     private final TimeScale timeScale;

  240.     /**
  241.      * Create an AEM writer that streams data to the given output stream.
  242.      *
  243.      * @param writer    The output stream for the AEM file. Most methods will append data
  244.      *                  to this {@code writer}.
  245.      * @param timeScale for all times in the AEM except {@link Keyword#CREATION_DATE}. See
  246.      *                  Section 4.2.5.4.2 and Annex A.
  247.      * @param metadata  for the satellite.
  248.      */
  249.     public StreamingAemWriter(final Appendable writer,
  250.                               final TimeScale timeScale,
  251.                               final Map<Keyword, String> metadata) {
  252.         this.writer    = writer;
  253.         this.timeScale = timeScale;
  254.         this.metadata  = new LinkedHashMap<>(metadata);

  256.         // Set default metadata
  257.         this.metadata.putIfAbsent(Keyword.CCSDS_AEM_VERS, CCSDS_AEM_VERS);

  259.         // creation date is informational only
  260.         this.metadata.putIfAbsent(Keyword.CREATION_DATE,
  261.                 ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_INSTANT));
  262.         this.metadata.putIfAbsent(Keyword.ORIGINATOR, DEFAULT_ORIGINATOR);
  263.         this.metadata.putIfAbsent(Keyword.TIME_SYSTEM, timeScale.getName());
  264.     }

  266.     /**
  267.      * Write a single key and value to the stream using Key Value Notation (KVN).
  268.      * @param key   the keyword to write
  269.      * @param value the value to write
  270.      * @throws IOException if an I/O error occurs.
  271.      */
  272.     private void writeKeyValue(final Keyword key, final String value) throws IOException {
  273.         writer.append(String.format(STANDARDIZED_LOCALE, KV_FORMAT, key.toString(), value));
  274.     }

  276.     /**
  277.      * Writes the standard AEM header for the file.
  278.      * @throws IOException if the stream cannot write to stream
  279.      */
  280.     public void writeHeader() throws IOException {
  281.         writeKeyValue(Keyword.CCSDS_AEM_VERS, this.metadata.get(Keyword.CCSDS_AEM_VERS));
  282.         final String comment = this.metadata.get(Keyword.COMMENT);
  283.         if (comment != null) {
  284.             writeKeyValue(Keyword.COMMENT, comment);
  285.         }
  286.         writeKeyValue(Keyword.CREATION_DATE, this.metadata.get(Keyword.CREATION_DATE));
  287.         writeKeyValue(Keyword.ORIGINATOR, this.metadata.get(Keyword.ORIGINATOR));
  288.         writer.append(NEW_LINE);
  289.     }

  291.     /**
  292.      * Create a writer for a new AEM attitude ephemeris segment.
  293.      * <p> The returned writer can only write a single attitude ephemeris segment in an AEM.
  294.      * This method must be called to create a writer for each attitude ephemeris segment.
  295.      * @param segmentMetadata the metadata to use for the segment. Overrides for this
  296.      *                        segment any other source of meta data values. See {@link
  297.      *                        #StreamingAemWriter} for a description of which metadata are
  298.      *                        required and how they are determined.
  299.      * @return a new AEM segment, ready for writing.
  300.      */
  301.     public AEMSegment newSegment(final Map<Keyword, String> segmentMetadata) {
  302.         final Map<Keyword, String> meta = new LinkedHashMap<>(this.metadata);
  303.         meta.putAll(segmentMetadata);
  304.         return new AEMSegment(meta);
  305.     }

  307.     /**
  308.      * Convert a date to a string with more precision.
  309.      *
  310.      * @param components to convert to a String.
  311.      * @return the String form of {@code date} with at least 9 digits of precision.
  312.      */
  313.     static String dateToString(final DateTimeComponents components) {
  314.         final TimeComponents time = components.getTime();
  315.         final int hour = time.getHour();
  316.         final int minute = time.getMinute();
  317.         final double second = time.getSecond();
  318.         // Decimal formatting classes could be static final if they were thread safe.
  319.         final DecimalFormatSymbols locale = new DecimalFormatSymbols(STANDARDIZED_LOCALE);
  320.         final DecimalFormat twoDigits = new DecimalFormat("00", locale);
  321.         final DecimalFormat precise = new DecimalFormat("00.0########", locale);
  322.         return components.getDate().toString() + "T" + twoDigits.format(hour) + ":" +
  323.                 twoDigits.format(minute) + ":" + precise.format(second);
  324.     }

  326.     /** A writer for a segment of an AEM. */
  327.     public class AEMSegment implements OrekitFixedStepHandler {

  329.         /** Metadata for this AEM Segment. */
  330.         private final Map<Keyword, String> metadata;

  332.         /**
  333.          * Create a new segment writer.
  334.          * @param metadata to use when writing this segment.
  335.          */
  336.         private AEMSegment(final Map<Keyword, String> metadata) {
  337.             this.metadata = metadata;
  338.         }

  340.         /**
  341.          * Write the ephemeris segment metadata.
  342.          *
  343.          * <p> See {@link StreamingAemWriter} for a description of how the metadata is
  344.          * set.
  345.          *
  346.          * @throws IOException if the output stream throws one while writing.
  347.          */
  348.         public void writeMetadata() throws IOException {
  349.             // Start metadata
  350.             writer.append("META_START").append(NEW_LINE);

  352.             // Table 4.3
  353.             writeKeyValue(Keyword.OBJECT_NAME,  this.metadata.get(Keyword.OBJECT_NAME));
  354.             writeKeyValue(Keyword.OBJECT_ID,    this.metadata.get(Keyword.OBJECT_ID));
  355.             writeKeyValue(Keyword.CENTER_NAME,  this.metadata.get(Keyword.CENTER_NAME));
  356.             writeKeyValue(Keyword.REF_FRAME_A,  this.metadata.get(Keyword.REF_FRAME_A));
  357.             writeKeyValue(Keyword.REF_FRAME_B,  this.metadata.get(Keyword.REF_FRAME_B));
  358.             writeKeyValue(Keyword.ATTITUDE_DIR, this.metadata.get(Keyword.ATTITUDE_DIR));
  359.             writeKeyValue(Keyword.TIME_SYSTEM,  this.metadata.get(Keyword.TIME_SYSTEM));
  360.             writeKeyValue(Keyword.START_TIME,   this.metadata.get(Keyword.START_TIME));

  362.             // Optional values: USEABLE_START_TIME & USEABLE_STOP_TIME
  363.             final String usableStartTime = this.metadata.get(Keyword.USEABLE_START_TIME);
  364.             if (usableStartTime != null) {
  365.                 writeKeyValue(Keyword.USEABLE_START_TIME, usableStartTime);
  366.             }
  367.             final String usableStopTime = this.metadata.get(Keyword.USEABLE_STOP_TIME);
  368.             if (usableStopTime != null) {
  369.                 writeKeyValue(Keyword.USEABLE_STOP_TIME, usableStopTime);
  370.             }

  372.             // Table 4.3
  373.             writeKeyValue(Keyword.STOP_TIME,     this.metadata.get(Keyword.STOP_TIME));
  374.             writeKeyValue(Keyword.ATTITUDE_TYPE, this.metadata.get(Keyword.ATTITUDE_TYPE));

  376.             // Optional values: QUATERNION_ TYPE; EULER_ROT_SEQ; RATE_FRAME; INTERPOLATION_METHOD and INTERPOLATION_DEGREE
  377.             final String quaternionType = this.metadata.get(Keyword.QUATERNION_TYPE);
  378.             if (quaternionType != null) {
  379.                 writeKeyValue(Keyword.QUATERNION_TYPE, quaternionType);
  380.             }
  381.             final String eulerRotSeq = this.metadata.get(Keyword.EULER_ROT_SEQ);
  382.             if (eulerRotSeq != null) {
  383.                 writeKeyValue(Keyword.EULER_ROT_SEQ, eulerRotSeq);
  384.             }
  385.             final String rateFrame = this.metadata.get(Keyword.RATE_FRAME);
  386.             if (rateFrame != null) {
  387.                 writeKeyValue(Keyword.RATE_FRAME, rateFrame);
  388.             }
  389.             final String interpolationMethod = this.metadata.get(Keyword.INTERPOLATION_METHOD);
  390.             if (interpolationMethod != null) {
  391.                 writeKeyValue(Keyword.INTERPOLATION_METHOD, interpolationMethod);
  392.             }
  393.             final String interpolationDegree = this.metadata.get(Keyword.INTERPOLATION_DEGREE);
  394.             if (interpolationDegree != null) {
  395.                 writeKeyValue(Keyword.INTERPOLATION_DEGREE, interpolationDegree);
  396.             }

  398.             // Stop metadata
  399.             writer.append("META_STOP").append(NEW_LINE).append(NEW_LINE);
  400.         }

  402.         /**
  403.          * Write a single attitude ephemeris line according to section 4.2.4 and Table 4-4.
  404.          * @param attitude the attitude information for a given date.
  405.          * @param isFirst true if QC is the first element in the attitude data
  406.          * @param attitudeName name of the attitude type
  407.          * @param rotationOrder rotation order
  408.          * @throws IOException if the output stream throws one while writing.
  409.          */
  410.         public void writeAttitudeEphemerisLine(final TimeStampedAngularCoordinates attitude,
  411.                                                final boolean isFirst,
  412.                                                final String attitudeName,
  413.                                                final RotationOrder rotationOrder)
  414.             throws IOException {
  415.             // Epoch
  416.             final String epoch = dateToString(attitude.getDate().getComponents(timeScale));
  417.             writer.append(epoch).append(" ");
  418.             // Attitude data in degrees
  419.             final AEMAttitudeType type = AEMAttitudeType.getAttitudeType(attitudeName);
  420.             final double[]        data = type.getAttitudeData(attitude, isFirst, rotationOrder);
  421.             final int             size = data.length;
  422.             for (int index = 0; index < size; index++) {
  423.                 writer.append(Double.toString(data[index]));
  424.                 final String space = (index == size - 1) ? "" : " ";
  425.                 writer.append(space);
  426.             }
  427.             // end the line
  428.             writer.append(NEW_LINE);
  429.         }

  431.         /**
  432.          * {@inheritDoc}
  433.          *
  434.          * <p> Sets the {@link Keyword#START_TIME} and {@link Keyword#STOP_TIME} in this
  435.          * segment's metadata if not already set by the user. Then calls {@link
  436.          * #writeMetadata()} to start the segment.
  437.          */
  438.         @Override
  439.         public void init(final SpacecraftState s0,
  440.                          final AbsoluteDate t,
  441.                          final double step) {
  442.             try {
  443.                 final String start = dateToString(s0.getDate().getComponents(timeScale));
  444.                 final String stop = dateToString(t.getComponents(timeScale));
  445.                 this.metadata.putIfAbsent(Keyword.START_TIME, start);
  446.                 this.metadata.putIfAbsent(Keyword.STOP_TIME, stop);
  447.                 this.writeMetadata();
  448.             } catch (IOException e) {
  449.                 throw new OrekitException(e, LocalizedCoreFormats.SIMPLE_MESSAGE,
  450.                         e.getLocalizedMessage());
  451.             }
  452.         }

  454.         /** {@inheritDoc}. */
  455.         @Override
  456.         public void handleStep(final SpacecraftState currentState, final boolean isLast) {
  457.             try {

  459.                 // Quaternion type
  460.                 final String quaternionType = this.metadata.get(Keyword.QUATERNION_TYPE);
  461.                 // If the QUATERNION_TYPE keyword is not present in the file, this means that
  462.                 // the attitude data are not given using quaternion. Therefore, the computation
  463.                 // of the attitude data will not be sensitive to this parameter. A default value
  464.                 // can be set
  465.                 boolean isFirst = false;
  466.                 if (quaternionType != null) {
  467.                     isFirst = (quaternionType.equals("FIRST")) ? true : false;
  468.                 }

  470.                 // Attitude type
  471.                 final String attitudeType = this.metadata.get(Keyword.ATTITUDE_TYPE);

  473.                 // Rotation order
  474.                 final String eulerRotSeq = this.metadata.get(Keyword.EULER_ROT_SEQ);
  475.                 final RotationOrder order = (eulerRotSeq == null) ? null : AEMRotationOrder.getRotationOrder(eulerRotSeq);

  477.                 // Write attitude ephemeris data
  478.                 writeAttitudeEphemerisLine(currentState.getAttitude().getOrientation(), isFirst,
  479.                                            attitudeType, order);

  481.             } catch (IOException e) {
  482.                 throw new OrekitException(e, LocalizedCoreFormats.SIMPLE_MESSAGE,
  483.                         e.getLocalizedMessage());
  484.             }

  486.         }

  488.         /**
  489.          * Start of an attitude block.
  490.          * @throws IOException if the output stream throws one while writing.
  491.          */
  492.         void startAttitudeBlock() throws IOException {
  493.             writer.append("DATA_START").append(NEW_LINE);
  494.         }

  496.         /**
  497.          * End of an attitude block.
  498.          * @throws IOException if the output stream throws one while writing.
  499.          */
  500.         void endAttitudeBlock() throws IOException {
  501.             writer.append("DATA_STOP").append(NEW_LINE);
  502.         }

  504.     }

  506. }
Created with JaCoCo 0.8.5.201910111838