ObservationType.java

  1. /* Copyright 2002-2024 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.ndm.tdm;

  19. import java.util.regex.Pattern;

  21. import org.orekit.errors.OrekitException;
  22. import org.orekit.errors.OrekitMessages;
  23. import org.orekit.files.ccsds.definitions.Units;
  24. import org.orekit.files.ccsds.utils.ContextBinding;
  25. import org.orekit.files.ccsds.utils.lexical.ParseToken;
  26. import org.orekit.files.ccsds.utils.lexical.TokenType;
  27. import org.orekit.time.AbsoluteDate;
  28. import org.orekit.utils.Constants;
  29. import org.orekit.utils.units.Unit;


  32. /** Keys for {@link Observation TDM observations} entries.
  33.  * @author Maxime Journot
  34.  * @since 11.0
  35.  */
  36. public enum ObservationType {

  38.     // Signal related keywords.
  39.     /** Data: Carrier power [dBW].<p>
  40.      *  Strength of the radio signal transmitted by the spacecraft as received at the ground station or at another spacecraft.
  41.      */
  42.     CARRIER_POWER(Unit.ONE),
  43.     /** Data: Doppler counts [n/a].<p>
  44.      *  Count of signal cycles.
  45.      */
  46.     DOPPLER_COUNT(Unit.ONE),
  47.     /** Data: Doppler instantaneous [km/s].<p>
  48.      *  Instantaneous range rate of the spacecraft.
  49.      */
  50.     DOPPLER_INSTANTANEOUS(Units.KM_PER_S),
  51.     /** Data: Doppler integrated [km/s].<p>
  52.      *  Mean range rate of the spacecraft over the INTEGRATION_INTERVAL specified in the meta-data section.
  53.      */
  54.     DOPPLER_INTEGRATED(Units.KM_PER_S),
  55.     /** Data: Carrier power to noise spectral density ratio (Pc/No) [dBHz]. */
  56.     PC_N0(Unit.ONE),
  57.     /** Data: Ranging power to noise spectral density ratio (Pr/No) [dBHz]. */
  58.     PR_N0(Unit.ONE),
  59.     /** Data: phase cycle count at receiver. */
  60.     RECEIVE_PHASE_CT_1(Unit.ONE),
  61.     /** Data: phase cycle count at receiver. */
  62.     RECEIVE_PHASE_CT_2(Unit.ONE),
  63.     /** Data: phase cycle count at receiver. */
  64.     RECEIVE_PHASE_CT_3(Unit.ONE),
  65.     /** Data: phase cycle count at receiver. */
  66.     RECEIVE_PHASE_CT_4(Unit.ONE),
  67.     /** Data: phase cycle count at receiver. */
  68.     RECEIVE_PHASE_CT_5(Unit.ONE),
  69.     /** Data: phase cycle count at transmitter. */
  70.     TRANSMIT_PHASE_CT_1(Unit.ONE),
  71.     /** Data: phase cycle count at transmitter. */
  72.     TRANSMIT_PHASE_CT_2(Unit.ONE),
  73.     /** Data: phase cycle count at transmitter. */
  74.     TRANSMIT_PHASE_CT_3(Unit.ONE),
  75.     /** Data: phase cycle count at transmitter. */
  76.     TRANSMIT_PHASE_CT_4(Unit.ONE),
  77.     /** Data: phase cycle count at transmitter. */
  78.     TRANSMIT_PHASE_CT_5(Unit.ONE),
  79.     /** Data: Range value [km, s or RU].
  80.      * @see RangeUnits
  81.      */
  82.     RANGE(Unit.KILOMETRE) {

  84.         /** {@inheritDoc}*/
  85.         @Override
  86.         public double rawToSI(final RangeUnitsConverter ruConverter, final TdmMetadata metadata,
  87.                               final AbsoluteDate date, final double rawValue) {
  88.             if (metadata.getRangeUnits() == RangeUnits.km) {
  89.                 return Unit.KILOMETRE.toSI(rawValue);
  90.             } else if (metadata.getRangeUnits() == RangeUnits.s) {
  91.                 return rawValue * Constants.SPEED_OF_LIGHT;
  92.             } else {
  93.                 if (ruConverter == null) {
  94.                     throw new OrekitException(OrekitMessages.CCSDS_TDM_MISSING_RANGE_UNITS_CONVERTER);
  95.                 }
  96.                 return ruConverter.ruToMeters(metadata, date, rawValue);
  97.             }
  98.         }

  100.         /** {@inheritDoc}*/
  101.         @Override
  102.         public double siToRaw(final RangeUnitsConverter ruConverter, final TdmMetadata metadata,
  103.                               final AbsoluteDate date, final double siValue) {
  104.             if (metadata.getRangeUnits() == RangeUnits.km) {
  105.                 return Unit.KILOMETRE.fromSI(siValue);
  106.             } else if (metadata.getRangeUnits() == RangeUnits.s) {
  107.                 return siValue / Constants.SPEED_OF_LIGHT;
  108.             } else {
  109.                 if (ruConverter == null) {
  110.                     throw new OrekitException(OrekitMessages.CCSDS_TDM_MISSING_RANGE_UNITS_CONVERTER);
  111.                 }
  112.                 return ruConverter.metersToRu(metadata, date, siValue);
  113.             }
  114.         }

  116.     },

  118.     /** Data: Received frequencies [Hz].<p>
  119.      * The RECEIVE_FREQ keyword shall be used to indicate that the values represent measurements of the received frequency.<p>
  120.      * The keyword is indexed to accommodate a scenario in which multiple downlinks are used.<p>
  121.      * RECEIVE_FREQ_n (n = 1, 2, 3, 4, 5)
  122.      */
  123.     RECEIVE_FREQ_1(Unit.HERTZ),
  124.     /** Received frequency 2. */
  125.     RECEIVE_FREQ_2(Unit.HERTZ),
  126.     /** Received frequency 3. */
  127.     RECEIVE_FREQ_3(Unit.HERTZ),
  128.     /** Received frequency 4. */
  129.     RECEIVE_FREQ_4(Unit.HERTZ),
  130.     /** Received frequency 5. */
  131.     RECEIVE_FREQ_5(Unit.HERTZ),
  132.     /** Data: Received frequency [Hz].<p>
  133.      *  Case without an index; where the frequency cannot be associated with a particular participant.
  134.      */
  135.     RECEIVE_FREQ(Unit.HERTZ),
  136.     /** Data: Transmitted frequencies [Hz].<p>
  137.      * The TRANSMIT_FREQ keyword shall be used to indicate that the values represent measurements of a transmitted frequency, e.g., from an uplink operation.<p>
  138.      * The TRANSMIT_FREQ keyword is indexed to accommodate scenarios in which multiple transmitters are used.<p>
  139.      * TRANSMIT_FREQ_n (n = 1, 2, 3, 4, 5)
  140.      */
  141.     TRANSMIT_FREQ_1(Unit.HERTZ),
  142.     /** Transmitted frequency 2. */
  143.     TRANSMIT_FREQ_2(Unit.HERTZ),
  144.     /** Transmitted frequency 3. */
  145.     TRANSMIT_FREQ_3(Unit.HERTZ),
  146.     /** Transmitted frequency 4. */
  147.     TRANSMIT_FREQ_4(Unit.HERTZ),
  148.     /** Transmitted frequency 5. */
  149.     TRANSMIT_FREQ_5(Unit.HERTZ),
  150.     /** Data: Transmitted frequencies rates [Hz/s].<p>
  151.      * The value associated with the TRANSMIT_FREQ_RATE_n keyword is the linear rate of
  152.      * change of the frequency TRANSMIT_FREQ_n starting at the timetag and continuing
  153.      *  until the next TRANSMIT_FREQ_RATE_n timetag (or until the end of the data).<p>
  154.      * TRANSMIT_FREQ_RATE_n (n = 1, 2, 3, 4, 5)
  155.      */
  156.     TRANSMIT_FREQ_RATE_1(Units.HZ_PER_S),
  157.     /** Transmitted frequency rate 2. */
  158.     TRANSMIT_FREQ_RATE_2(Units.HZ_PER_S),
  159.     /** Transmitted frequency rate 3. */
  160.     TRANSMIT_FREQ_RATE_3(Units.HZ_PER_S),
  161.     /** Transmitted frequency rate 4. */
  162.     TRANSMIT_FREQ_RATE_4(Units.HZ_PER_S),
  163.     /** Transmitted frequency rate 5. */
  164.     TRANSMIT_FREQ_RATE_5(Units.HZ_PER_S),

  166.     // VLBI/Delta-DOR Related Keywords
  167.     /** Data: DOR [s].<p>
  168.      * the DOR keyword represents the range measured via PATH_2 minus the range measured via PATH_1.
  169.      */
  170.     DOR(Unit.SECOND),
  171.     /** Data: VLBI delay [s].<p>
  172.      * The observable associated with the VLBI_DELAY keyword represents the time of signal
  173.      * arrival via PATH_2 minus the time of signal arrival via PATH_1.
  174.      */
  175.     VLBI_DELAY(Unit.SECOND),

  177.     // Angle Related Keywords
  178.     /** Data: ANGLE_1 in degrees and in [-180, +360[ [deg].<p>
  179.      * The value assigned to the ANGLE_1 keyword represents the azimuth, right ascension, or ‘X’
  180.      * angle of the measurement, depending on the value of the ANGLE_TYPE keyword.<p>
  181.      * The angle measurement shall be a double precision value as follows: -180.0 &le; ANGLE_1 &lt; 360.0<p>
  182.      * Units shall be degrees.<p>
  183.      * See meta-data keyword ANGLE_TYPE for the definition of the angles.
  184.      */
  185.     ANGLE_1(Unit.DEGREE),
  186.     /** Data: ANGLE_2 in degrees and in [-180, +360[ [deg].<p>
  187.      * The value assigned to the ANGLE_2 keyword represents the elevation, declination, or ‘Y’
  188.      * angle of the measurement, depending on the value of the ANGLE_TYPE keyword.<p>
  189.      * The angle measurement shall be a double precision value as follows: -180.0 &le; ANGLE_2 &lt; 360.0.<p>
  190.      * Units shall be degrees.<p>
  191.      * See meta-data keyword ANGLE_TYPE for the definition of the angles.
  192.      */
  193.     ANGLE_2(Unit.DEGREE),

  195.     // Optical/Radar Related keywords
  196.     /** Data: visual magnitude. */
  197.     MAG(Unit.ONE),
  198.     /** Data: Radar Cross section [m²]. */
  199.     RCS(Units.M2),

  201.     // Time Related Keywords
  202.     /** Data: Clock bias [s].<p>
  203.      * The CLOCK_BIAS keyword can be used by the message recipient to adjust timetag
  204.      * measurements by a specified amount with respect to a common reference.
  205.      */
  206.     CLOCK_BIAS(Unit.SECOND),
  207.     /** Data: Clock drift [s/s].<p>
  208.      * The CLOCK_DRIFT keyword should be used to adjust timetag measurements by an amount that is a function of time with
  209.      * respect to a common reference, normally UTC (as opposed to the CLOCK_BIAS, which is meant to be a constant adjustment).
  210.      */
  211.     CLOCK_DRIFT(Unit.ONE),

  213.     // Media Related Keywords
  214.     /** Data: STEC - Slant Total Electron Count [TECU].
  215.      * The STEC keyword shall be used to convey the line of sight,
  216.      * one way charged particle delay or total electron count (TEC) at the timetag associated with a
  217.      * tracking measurement, which is calculated by integrating the electron density along the
  218.      * propagation path (electrons/m2).
  219.      */
  220.     STEC(Unit.TOTAL_ELECTRON_CONTENT_UNIT),
  221.     /** Data: TROPO DRY [m].<p>
  222.      * Dry zenith delay through the troposphere measured at the timetag.
  223.      */
  224.     TROPO_DRY(Unit.METRE),
  225.     /** Data: TROPO WET [m].<p>
  226.      * Wet zenith delay through the troposphere measured at the timetag.
  227.      */
  228.     TROPO_WET(Unit.METRE),

  230.     // Meteorological Related Keywords
  231.     /** Data: Pressure [hPa].<p>
  232.      * Atmospheric pressure observable as measured at the tracking participant.
  233.      */
  234.     PRESSURE(Units.HECTO_PASCAL),
  235.     /** Data: Relative humidity [%].<p>
  236.      * Relative humidity observable as measured at the tracking participant.
  237.      */
  238.     RHUMIDITY(Unit.PERCENT),
  239.     /** Data: Temperature [K].<p>
  240.      * Temperature observable as measured at the tracking participant.
  241.      */
  242.     TEMPERATURE(Unit.ONE);

  244.     /** Pattern for delimiting regular expressions. */
  245.     private static final Pattern SEPARATOR = Pattern.compile("\\s+");

  247.     /** Unit. */
  248.     private final Unit unit;

  250.     /** Simple constructor.
  251.      * @param unit observation unit
  252.      */
  253.     ObservationType(final Unit unit) {
  254.         this.unit = unit;
  255.     }

  257.     /** Process an observation line.
  258.      * @param token parse token
  259.      * @param context context binding
  260.      * @param ruConverter converter for {@link RangeUnits#RU Range Units} (may be null)
  261.      * @param metadata metadata for current block
  262.      * @param observationsBlock observation block to fill
  263.      * @return true if token was accepted
  264.      */
  265.     public boolean process(final ParseToken token, final ContextBinding context,
  266.                            final RangeUnitsConverter ruConverter, final TdmMetadata metadata,
  267.                            final ObservationsBlock observationsBlock) {

  269.         if (token.getType() == TokenType.ENTRY) {
  270.             // in an XML file, an observation element contains only the value, the epoch has been parsed before
  271.             // in a KVN file, an observation line should contains both epoch and value

  273.             if (observationsBlock.getCurrentObservationEpoch() != null) {
  274.                 // we are parsing an XML file with epoch already parsed
  275.                 // parse the measurement
  276.                 final AbsoluteDate epoch    = observationsBlock.getCurrentObservationEpoch();
  277.                 final double       rawValue = token.getContentAsDouble();
  278.                 observationsBlock.addObservationValue(this, rawToSI(ruConverter, metadata, epoch, rawValue));
  279.             } else {

  281.                 // we are parsing a KVN file and need to parse both epoch and measurement
  282.                 final String[] fields = SEPARATOR.split(token.getContentAsNormalizedString());
  283.                 if (fields.length != 2) {
  284.                     throw token.generateException(null);
  285.                 }
  286.                 // parse the epoch
  287.                 final AbsoluteDate epoch = context.getTimeSystem().getConverter(context).parse(fields[0]);
  288.                 observationsBlock.addObservationEpoch(epoch);

  290.                 // parse the measurement
  291.                 try {
  292.                     final double rawValue = Double.parseDouble(fields[1]);
  293.                     observationsBlock.addObservationValue(this, rawToSI(ruConverter, metadata, epoch, rawValue));
  294.                 } catch (NumberFormatException nfe) {
  295.                     throw token.generateException(nfe);
  296.                 }
  297.             }
  298.         }

  300.         return true;

  302.     }

  304.     /** Convert a measurement to SI units.
  305.      * @param ruConverter converter for {@link RangeUnits#RU Range Units} (may be null)
  306.      * @param metadata metadata corresponding to the observation
  307.      * @param date observation date
  308.      * @param rawValue measurement raw value
  309.      * @return measurement in SI units
  310.      */
  311.     public double rawToSI(final RangeUnitsConverter ruConverter, final TdmMetadata metadata,
  312.                           final AbsoluteDate date, final double rawValue) {
  313.         return unit.toSI(rawValue);
  314.     }

  316.     /** Convert a measurement from SI units.
  317.      * @param ruConverter converter for {@link RangeUnits#RU Range Units} (may be null)
  318.      * @param metadata metadata corresponding to the observation
  319.      * @param date observation date
  320.      * @param siValue measurement value in SI units
  321.      * @return measurement raw value
  322.      */
  323.     public double siToRaw(final RangeUnitsConverter ruConverter, final TdmMetadata metadata,
  324.                           final AbsoluteDate date, final double siValue) {
  325.         return unit.fromSI(siValue);
  326.     }

  328. }
Created with JaCoCo 0.8.12.202403310830