RuggedBuilder.java

  1. /* Copyright 2013-2022 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.rugged.api;

  19. import java.io.IOException;
  20. import java.io.InputStream;
  21. import java.io.ObjectInputStream;
  22. import java.io.ObjectOutputStream;
  23. import java.io.OutputStream;
  24. import java.util.ArrayList;
  25. import java.util.Collections;
  26. import java.util.List;

  28. import org.hipparchus.exception.LocalizedCoreFormats;
  29. import org.hipparchus.geometry.euclidean.threed.Rotation;
  30. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  31. import org.orekit.bodies.OneAxisEllipsoid;
  32. import org.orekit.frames.Frame;
  33. import org.orekit.frames.FramesFactory;
  34. import org.orekit.propagation.Propagator;
  35. import org.orekit.rugged.errors.RuggedException;
  36. import org.orekit.rugged.errors.RuggedInternalError;
  37. import org.orekit.rugged.errors.RuggedMessages;
  38. import org.orekit.rugged.intersection.BasicScanAlgorithm;
  39. import org.orekit.rugged.intersection.ConstantElevationAlgorithm;
  40. import org.orekit.rugged.intersection.IgnoreDEMAlgorithm;
  41. import org.orekit.rugged.intersection.IntersectionAlgorithm;
  42. import org.orekit.rugged.intersection.duvenhage.DuvenhageAlgorithm;
  43. import org.orekit.rugged.linesensor.LineSensor;
  44. import org.orekit.rugged.raster.TileUpdater;
  45. import org.orekit.rugged.refraction.AtmosphericRefraction;
  46. import org.orekit.rugged.utils.ExtendedEllipsoid;
  47. import org.orekit.rugged.utils.SpacecraftToObservedBody;
  48. import org.orekit.time.AbsoluteDate;
  49. import org.orekit.utils.AngularDerivativesFilter;
  50. import org.orekit.utils.CartesianDerivativesFilter;
  51. import org.orekit.utils.Constants;
  52. import org.orekit.utils.IERSConventions;
  53. import org.orekit.utils.PVCoordinates;
  54. import org.orekit.utils.TimeStampedAngularCoordinates;
  55. import org.orekit.utils.TimeStampedPVCoordinates;

  57. /** Builder for {@link Rugged} instances.
  58.  * <p>
  59.  * This class implements the <em>builder pattern</em> to create {@link Rugged} instances.
  60.  * It does so by using a <em>fluent API</em> in order to clarify reading and allow
  61.  * later extensions with new configuration parameters.
  62.  * </p>
  63.  * <p>
  64.  * A typical use would be:
  65.  * </p>
  66.  * <pre>
  67.  *   Rugged rugged = new RuggedBuilder().
  68.  *                   setEllipsoid(EllipsoidId.WGS84, BodyRotatingFrameId.ITRF).
  69.  *                   setAlgorithmID(AlgorithmId.Duvenhage).
  70.  *                   setDigitalElevationModel(tileUpdater, maxCachedTiles).
  71.  *                   setTimeSpan(minDate, maxDate, tStep, overshootTolerance).
  72.  *                   setTrajectory(positionsVelocities, pvInterpolationNumber, pvFilter,
  73.  *                                 quaternions, aInterpolationNumber, aFilter).
  74.  *                   addLineSensor(sensor1).
  75.  *                   addLineSensor(sensor2).
  76.  *                   addLineSensor(sensor3).
  77.  *                   build();
  78.  * </pre>
  79.  * <p>
  80.  * If a configuration parameter has not been set prior to the call to {]link #build()}, then
  81.  * an exception will be triggered with an explicit error message.
  82.  * </p>
  83.  * @see <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder pattern (wikipedia)</a>
  84.  * @see <a href="https://en.wikipedia.org/wiki/Fluent_interface">Fluent interface (wikipedia)</a>
  85.  * @author Luc Maisonobe
  86.  * @author Guylaine Prat
  87.  */
  88. public class RuggedBuilder {

  90.     /** Reference ellipsoid. */
  91.     private ExtendedEllipsoid ellipsoid;

  93.     /** DEM intersection algorithm. */
  94.     private AlgorithmId algorithmID;

  96.     /** Updater used to load Digital Elevation Model tiles. */
  97.     private TileUpdater tileUpdater;

  99.     /** Constant elevation over ellipsoid (m).
  100.      * used only with {@link AlgorithmId#CONSTANT_ELEVATION_OVER_ELLIPSOID. */
  101.     private double constantElevation;

  103.     /** Maximum number of tiles stored in the cache. */
  104.     private int maxCachedTiles;

  106.     /** Start of search time span. */
  107.     private AbsoluteDate minDate;

  109.     /** End of search time span. */
  110.     private AbsoluteDate maxDate;

  112.     /** Step to use for inertial frame to body frame transforms cache computations (s). */
  113.     private double tStep;

  115.     /** OvershootTolerance tolerance in seconds allowed for {@code minDate} and {@code maxDate} overshooting (s). */
  116.     private double overshootTolerance;

  118.     /** Inertial frame for position/velocity/attitude. */
  119.     private Frame inertial;

  121.     /** Satellite position and velocity (m and m/s in inertial frame). */
  122.     private List<TimeStampedPVCoordinates> pvSample;

  124.     /** Number of points to use for position/velocity interpolation. */
  125.     private int pvNeighborsSize;

  127.     /** Filter for derivatives from the sample to use in position/velocity interpolation. */
  128.     private CartesianDerivativesFilter pvDerivatives;

  130.     /** Satellite quaternions with respect to inertial frame. */
  131.     private List<TimeStampedAngularCoordinates> aSample;

  133.     /** Number of points to use for attitude interpolation. */
  134.     private int aNeighborsSize;

  136.     /** Filter for derivatives from the sample to use in attitude interpolation. */
  137.     private AngularDerivativesFilter aDerivatives;

  139.     /** Propagator for position/velocity/attitude. */
  140.     private Propagator pvaPropagator;

  142.     /** Step to use for inertial/Earth/spacecraft transforms interpolations (s). */
  143.     private double iStep;

  145.     /** Number of points to use for inertial/Earth/spacecraft transforms interpolations. */
  146.     private int iN;

  148.     /** Converter between spacecraft and body. */
  149.     private SpacecraftToObservedBody scToBody;

  151.     /** Flag for light time correction. */
  152.     private boolean lightTimeCorrection;

  154.     /** Flag for aberration of light correction. */
  155.     private boolean aberrationOfLightCorrection;

  157.     /** Atmospheric refraction to use for line of sight correction. */
  158.     private AtmosphericRefraction atmosphericRefraction;

  160.     /** Sensors. */
  161.     private final List<LineSensor> sensors;

  163.     /** Rugged name. */
  164.     private String name;

  166.     /** Create a non-configured builder.
  167.      * <p>
  168.      * The builder <em>must</em> be configured before calling the
  169.      * {@link #build} method, otherwise an exception will be triggered
  170.      * at build time.
  171.      * </p>
  172.      */
  173.     public RuggedBuilder() {
  174.         sensors                     = new ArrayList<>();
  175.         constantElevation           = Double.NaN;
  176.         lightTimeCorrection         = true;
  177.         aberrationOfLightCorrection = true;
  178.         name                        = "Rugged";
  179.     }

  181.     /** Set the reference ellipsoid.
  182.      * @param ellipsoidID reference ellipsoid
  183.      * @param bodyRotatingFrameID body rotating frame identifier
  184.      * from an earlier run and frames mismatch
  185.      * @return the builder instance
  186.      * @see #setEllipsoid(OneAxisEllipsoid)
  187.      * @see #getEllipsoid()
  188.      */
  189.     public RuggedBuilder setEllipsoid(final EllipsoidId ellipsoidID, final BodyRotatingFrameId bodyRotatingFrameID) {
  190.         return setEllipsoid(selectEllipsoid(ellipsoidID, selectBodyRotatingFrame(bodyRotatingFrameID)));
  191.     }

  193.     /** Set the reference ellipsoid.
  194.      * @param newEllipsoid reference ellipsoid
  195.      * @return the builder instance
  196.      * @see #setEllipsoid(EllipsoidId, BodyRotatingFrameId)
  197.      * @see #getEllipsoid()
  198.      */
  199.     public RuggedBuilder setEllipsoid(final OneAxisEllipsoid newEllipsoid) {
  200.         this.ellipsoid = new ExtendedEllipsoid(newEllipsoid.getEquatorialRadius(),
  201.                                                newEllipsoid.getFlattening(),
  202.                                                newEllipsoid.getBodyFrame());
  203.         checkFramesConsistency();
  204.         return this;
  205.     }

  207.     /** Get the ellipsoid.
  208.      * @return the ellipsoid
  209.      * @see #setEllipsoid(EllipsoidId, BodyRotatingFrameId)
  210.      * @see #setEllipsoid(OneAxisEllipsoid)
  211.      */
  212.     public ExtendedEllipsoid getEllipsoid() {
  213.         return ellipsoid;
  214.     }

  216.     /** Get the Rugged name.
  217.      * @return the Rugged name
  218.      * @since 2.0
  219.      */
  220.     public String getName() {
  221.         return name;
  222.     }

  224.     /** Set the Rugged name.
  225.      * @param name the Rugged name
  226.      * @since 2.0
  227.      */
  228.     public void setName(final String name) {
  229.         this.name = name;
  230.     }

  232.     /** Set the algorithm to use for Digital Elevation Model intersection.
  233.      * <p>
  234.      * Note that some algorithms require specific other methods to be called too:
  235.      * <ul>
  236.      *   <li>{@link AlgorithmId#DUVENHAGE DUVENHAGE},
  237.      *   {@link AlgorithmId#DUVENHAGE_FLAT_BODY DUVENHAGE_FLAT_BODY}
  238.      *   and {@link AlgorithmId#BASIC_SLOW_EXHAUSTIVE_SCAN_FOR_TESTS_ONLY
  239.      *   BASIC_SLOW_EXHAUSTIVE_SCAN_FOR_TESTS_ONLY} all
  240.      *   require {@link #setDigitalElevationModel(TileUpdater, int) setDigitalElevationModel}
  241.      *   to be called,</li>
  242.      *   <li>{@link AlgorithmId#CONSTANT_ELEVATION_OVER_ELLIPSOID
  243.      *   CONSTANT_ELEVATION_OVER_ELLIPSOID} requires
  244.      *   {@link #setConstantElevation(double) setConstantElevation} to be called,</li>
  245.      *   <li>{@link AlgorithmId#IGNORE_DEM_USE_ELLIPSOID
  246.      *   IGNORE_DEM_USE_ELLIPSOID} does not require
  247.      *   any methods tobe called.</li>
  248.      * </ul>
  249.      *
  250.      * @param newAlgorithmId identifier of algorithm to use for Digital Elevation Model intersection
  251.      * @return the builder instance
  252.      * @see #setDigitalElevationModel(TileUpdater, int)
  253.      * @see #getAlgorithm()
  254.      */
  255.     public RuggedBuilder setAlgorithm(final AlgorithmId newAlgorithmId) {
  256.         this.algorithmID = newAlgorithmId;
  257.         return this;
  258.     }

  260.     /** Get the algorithm to use for Digital Elevation Model intersection.
  261.      * @return algorithm to use for Digital Elevation Model intersection
  262.      * @see #setAlgorithm(AlgorithmId)
  263.      */
  264.     public AlgorithmId getAlgorithm() {
  265.         return algorithmID;
  266.     }

  268.     /** Set the user-provided {@link TileUpdater tile updater}.
  269.      * <p>
  270.      * Note that when the algorithm specified in {@link #setAlgorithm(AlgorithmId)}
  271.      * is either {@link AlgorithmId#CONSTANT_ELEVATION_OVER_ELLIPSOID
  272.      * CONSTANT_ELEVATION_OVER_ELLIPSOID} or {@link
  273.      * AlgorithmId#IGNORE_DEM_USE_ELLIPSOID IGNORE_DEM_USE_ELLIPSOID},
  274.      * then this method becomes irrelevant and can either be not called at all,
  275.      * or it can be called with an updater set to {@code null}. For all other
  276.      * algorithms, the updater must be properly configured.
  277.      * </p>
  278.      * @param newTileUpdater updater used to load Digital Elevation Model tiles
  279.      * @param newMaxCachedTiles maximum number of tiles stored in the cache
  280.      * @return the builder instance
  281.      * @see #setAlgorithm(AlgorithmId)
  282.      * @see #getTileUpdater()
  283.      * @see #getMaxCachedTiles()
  284.      */
  285.     public RuggedBuilder setDigitalElevationModel(final TileUpdater newTileUpdater, final int newMaxCachedTiles) {
  286.         this.tileUpdater    = newTileUpdater;
  287.         this.maxCachedTiles = newMaxCachedTiles;
  288.         return this;
  289.     }

  291.     /** Get the updater used to load Digital Elevation Model tiles.
  292.      * @return updater used to load Digital Elevation Model tiles
  293.      * @see #setDigitalElevationModel(TileUpdater, int)
  294.      * @see #getMaxCachedTiles()
  295.      */
  296.     public TileUpdater getTileUpdater() {
  297.         return tileUpdater;
  298.     }

  300.     /** Set the user-provided constant elevation model.
  301.      * <p>
  302.      * Note that this method is relevant <em>only</em> if the algorithm specified
  303.      * in {@link #setAlgorithm(AlgorithmId)} is {@link
  304.      * AlgorithmId#CONSTANT_ELEVATION_OVER_ELLIPSOID CONSTANT_ELEVATION_OVER_ELLIPSOID}.
  305.      * If it is called for another algorithm, the elevation set here will be ignored.
  306.      * </p>
  307.      * @param newConstantElevation constant elevation to use (m)
  308.      * @return the builder instance
  309.      * @see #setAlgorithm(AlgorithmId)
  310.      * @see #getConstantElevation()
  311.      */
  312.     public RuggedBuilder setConstantElevation(final double newConstantElevation) {
  313.         this.constantElevation = newConstantElevation;
  314.         return this;
  315.     }

  317.     /** Get the constant elevation over ellipsoid to use with {@link AlgorithmId#CONSTANT_ELEVATION_OVER_ELLIPSOID}.
  318.      * @return updater used to load Digital Elevation Model tiles
  319.      * @see #setConstantElevation(double)
  320.      */
  321.     public double getConstantElevation() {
  322.         return constantElevation;
  323.     }

  325.     /** Get the maximum number of tiles stored in the cache.
  326.      * @return maximum number of tiles stored in the cache
  327.      * @see #setDigitalElevationModel(TileUpdater, int)
  328.      * @see #getTileUpdater()
  329.      */
  330.     public int getMaxCachedTiles() {
  331.         return maxCachedTiles;
  332.     }

  334.     /** Set the time span to be covered for direct and inverse location calls.
  335.      * <p>
  336.      * This method set only the time span and not the trajectory, therefore it
  337.      * <em>must</em> be used together with either
  338.      * {@link #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)},
  339.      * {@link #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)},
  340.      * or {@link #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)}
  341.      * but should <em>not</em> be mixed with {@link #setTrajectoryAndTimeSpan(InputStream)}.
  342.      * </p>
  343.      * @param newMinDate start of search time span
  344.      * @param newMaxDate end of search time span
  345.      * @param newTstep step to use for inertial frame to body frame transforms cache computations (s)
  346.      * @param newOvershootTolerance tolerance in seconds allowed for {@code minDate} and {@code maxDate} overshooting (s)
  347.      * @return the builder instance
  348.      * @see #setTrajectoryAndTimeSpan(InputStream)
  349.      * @see #getMinDate()
  350.      * @see #getMaxDate()
  351.      * @see #getTStep()
  352.      * @see #getOvershootTolerance()
  353.      */
  354.     public RuggedBuilder setTimeSpan(final AbsoluteDate newMinDate, final AbsoluteDate newMaxDate,
  355.                                      final double newTstep, final double newOvershootTolerance) {
  356.         this.minDate            = newMinDate;
  357.         this.maxDate            = newMaxDate;
  358.         this.tStep              = newTstep;
  359.         this.overshootTolerance = newOvershootTolerance;
  360.         this.scToBody           = null;
  361.         return this;
  362.     }

  364.     /** Get the start of search time span.
  365.      * @return start of search time span
  366.      * @see #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)
  367.      */
  368.     public AbsoluteDate getMinDate() {
  369.         return minDate;
  370.     }

  372.     /** Get the end of search time span.
  373.      * @return end of search time span
  374.      * @see #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)
  375.      */
  376.     public AbsoluteDate getMaxDate() {
  377.         return maxDate;
  378.     }

  380.     /** Get the step to use for inertial frame to body frame transforms cache computations.
  381.      * @return step to use for inertial frame to body frame transforms cache computations
  382.      * @see #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)
  383.      */
  384.     public double getTStep() {
  385.         return tStep;
  386.     }

  388.     /** Get the tolerance in seconds allowed for {@link #getMinDate()} and {@link #getMaxDate()} overshooting.
  389.      * @return tolerance in seconds allowed for {@link #getMinDate()} and {@link #getMaxDate()} overshooting
  390.      * @see #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)
  391.      */
  392.     public double getOvershootTolerance() {
  393.         return overshootTolerance;
  394.     }

  396.     /** Set the spacecraft trajectory.
  397.      * <p>
  398.      * This method set only the trajectory and not the time span, therefore it
  399.      * <em>must</em> be used together with the {@link #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)}
  400.      * but should <em>not</em> be mixed with {@link #setTrajectoryAndTimeSpan(InputStream)}.
  401.      * </p>
  402.      * @param inertialFrameId inertial frame Id used for spacecraft positions/velocities/quaternions
  403.      * @param positionsVelocities satellite position and velocity (m and m/s in inertial frame)
  404.      * @param pvInterpolationNumber number of points to use for position/velocity interpolation
  405.      * @param pvFilter filter for derivatives from the sample to use in position/velocity interpolation
  406.      * @param quaternions satellite quaternions with respect to inertial frame
  407.      * @param aInterpolationNumber number of points to use for attitude interpolation
  408.      * @param aFilter filter for derivatives from the sample to use in attitude interpolation
  409.      * @return the builder instance
  410.      * @see #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  411.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  412.      * @see #setTrajectoryAndTimeSpan(InputStream)
  413.      * @see #getInertialFrame()
  414.      * @see #getPositionsVelocities()
  415.      * @see #getPVInterpolationNumber()
  416.      * @see #getPVInterpolationNumber()
  417.      * @see #getQuaternions()
  418.      * @see #getAInterpolationNumber()
  419.      * @see #getAFilter()
  420.      */
  421.     public RuggedBuilder setTrajectory(final InertialFrameId inertialFrameId,
  422.                                        final List<TimeStampedPVCoordinates> positionsVelocities, final int pvInterpolationNumber,
  423.                                        final CartesianDerivativesFilter pvFilter,
  424.                                        final List<TimeStampedAngularCoordinates> quaternions, final int aInterpolationNumber,
  425.                                        final AngularDerivativesFilter aFilter) {

  427.         return setTrajectory(selectInertialFrame(inertialFrameId),
  428.                              positionsVelocities, pvInterpolationNumber, pvFilter,
  429.                              quaternions, aInterpolationNumber, aFilter);
  430.     }

  432.     /** Set the spacecraft trajectory.
  433.      * <p>
  434.      * This method set only the trajectory and not the time span, therefore it
  435.      * <em>must</em> be used together with the {@link #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)}
  436.      * but should <em>not</em> be mixed with {@link #setTrajectoryAndTimeSpan(InputStream)}.
  437.      * </p>
  438.      * @param inertialFrame inertial frame used for spacecraft positions/velocities/quaternions
  439.      * @param positionsVelocities satellite position and velocity (m and m/s in inertial frame)
  440.      * @param pvInterpolationNumber number of points to use for position/velocity interpolation
  441.      * @param pvFilter filter for derivatives from the sample to use in position/velocity interpolation
  442.      * @param quaternions satellite quaternions with respect to inertial frame
  443.      * @param aInterpolationNumber number of points to use for attitude interpolation
  444.      * @param aFilter filter for derivatives from the sample to use in attitude interpolation
  445.      * @return the builder instance
  446.      * @see #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  447.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  448.      * @see #setTrajectoryAndTimeSpan(InputStream)
  449.      * @see #getPositionsVelocities()
  450.      * @see #getPVInterpolationNumber()
  451.      * @see #getPVInterpolationNumber()
  452.      * @see #getQuaternions()
  453.      * @see #getAInterpolationNumber()
  454.      * @see #getAFilter()
  455.      */
  456.     public RuggedBuilder setTrajectory(final Frame inertialFrame,
  457.                                        final List<TimeStampedPVCoordinates> positionsVelocities, final int pvInterpolationNumber,
  458.                                        final CartesianDerivativesFilter pvFilter,
  459.                                        final List<TimeStampedAngularCoordinates> quaternions, final int aInterpolationNumber,
  460.                                        final AngularDerivativesFilter aFilter) {

  462.         this.inertial        = inertialFrame;
  463.         this.pvSample        = positionsVelocities;
  464.         this.pvNeighborsSize = pvInterpolationNumber;
  465.         this.pvDerivatives   = pvFilter;
  466.         this.aSample         = quaternions;
  467.         this.aNeighborsSize  = aInterpolationNumber;
  468.         this.aDerivatives    = aFilter;
  469.         this.pvaPropagator   = null;
  470.         this.iStep           = Double.NaN;
  471.         this.iN              = -1;
  472.         this.scToBody        = null;
  473.         return this;
  474.     }

  476.     /** Set the spacecraft trajectory.
  477.      * <p>
  478.      * This method set only the trajectory and not the time span, therefore it
  479.      * <em>must</em> be used together with the {@link #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)}
  480.      * but should <em>not</em> be mixed with {@link #setTrajectoryAndTimeSpan(InputStream)}.
  481.      * </p>
  482.      * @param interpolationStep step to use for inertial/Earth/spacecraft transforms interpolations (s)
  483.      * @param interpolationNumber number of points to use for inertial/Earth/spacecraft transforms interpolations
  484.      * @param pvFilter filter for derivatives from the sample to use in position/velocity interpolation
  485.      * @param aFilter filter for derivatives from the sample to use in attitude interpolation
  486.      * @param propagator global propagator
  487.      * @return the builder instance
  488.      * @see #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  489.      * @see #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  490.      * @see #setTrajectoryAndTimeSpan(InputStream)
  491.      */
  492.     public RuggedBuilder setTrajectory(final double interpolationStep, final int interpolationNumber,
  493.                                        final CartesianDerivativesFilter pvFilter, final AngularDerivativesFilter aFilter,
  494.                                        final Propagator propagator) {
  495.         this.inertial        = propagator.getFrame();
  496.         this.pvSample        = null;
  497.         this.pvNeighborsSize = -1;
  498.         this.pvDerivatives   = pvFilter;
  499.         this.aSample         = null;
  500.         this.aNeighborsSize  = -1;
  501.         this.aDerivatives    = aFilter;
  502.         this.pvaPropagator   = propagator;
  503.         this.iStep           = interpolationStep;
  504.         this.iN              = interpolationNumber;
  505.         this.scToBody        = null;
  506.         return this;
  507.     }

  509.     /** Get the inertial frame.
  510.      * @return inertial frame
  511.      */
  512.     public Frame getInertialFrame() {
  513.         return inertial;
  514.     }

  516.     /** Get the satellite position and velocity (m and m/s in inertial frame).
  517.      * @return satellite position and velocity (m and m/s in inertial frame)
  518.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  519.      */
  520.     public List<TimeStampedPVCoordinates> getPositionsVelocities() {
  521.         return pvSample;
  522.     }

  524.     /** Get the number of points to use for position/velocity interpolation.
  525.      * @return number of points to use for position/velocity interpolation
  526.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  527.      */
  528.     public int getPVInterpolationNumber() {
  529.         return pvNeighborsSize;
  530.     }

  532.     /** Get the filter for derivatives from the sample to use in position/velocity interpolation.
  533.      * @return filter for derivatives from the sample to use in position/velocity interpolation
  534.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  535.      */
  536.     public CartesianDerivativesFilter getPVFilter() {
  537.         return pvDerivatives;
  538.     }

  540.     /** Get the satellite quaternions with respect to inertial frame.
  541.      * @return satellite quaternions with respect to inertial frame
  542.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  543.      */
  544.     public List<TimeStampedAngularCoordinates> getQuaternions() {
  545.         return aSample;
  546.     }

  548.     /** Get the number of points to use for attitude interpolation.
  549.      * @return number of points to use for attitude interpolation
  550.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  551.      */
  552.     public int getAInterpolationNumber() {
  553.         return aNeighborsSize;
  554.     }

  556.     /** Get the filter for derivatives from the sample to use in attitude interpolation.
  557.      * @return filter for derivatives from the sample to use in attitude interpolation
  558.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  559.      */
  560.     public AngularDerivativesFilter getAFilter() {
  561.         return aDerivatives;
  562.     }

  564.     /** Set both the spacecraft trajectory and the time span.
  565.      * <p>
  566.      * This method set both the trajectory and the time span in a tightly coupled
  567.      * way, therefore it should <em>not</em> be mixed with the individual methods
  568.      * {@link #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)},
  569.      * {@link #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)},
  570.      * {@link #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)},
  571.      * or {@link #setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)}.
  572.      * </p>
  573.      * @param storageStream stream from where to read previous instance {@link #storeInterpolator(OutputStream)
  574.      * stored interpolator} (caller opened it and remains responsible for closing it)
  575.      * @return the builder instance
  576.      * @see #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  577.      * @see #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  578.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  579.      * @see #storeInterpolator(OutputStream)
  580.      */
  581.     public RuggedBuilder setTrajectoryAndTimeSpan(final InputStream storageStream) {

  583.         try {
  584.             this.inertial           = null;
  585.             this.pvSample           = null;
  586.             this.pvNeighborsSize    = -1;
  587.             this.pvDerivatives      = null;
  588.             this.aSample            = null;
  589.             this.aNeighborsSize     = -1;
  590.             this.aDerivatives       = null;
  591.             this.pvaPropagator      = null;
  592.             this.iStep              = Double.NaN;
  593.             this.iN                 = -1;
  594.             this.scToBody           = (SpacecraftToObservedBody) new ObjectInputStream(storageStream).readObject();
  595.             this.minDate            = scToBody.getMinDate();
  596.             this.maxDate            = scToBody.getMaxDate();
  597.             this.tStep              = scToBody.getTStep();
  598.             this.overshootTolerance = scToBody.getOvershootTolerance();
  599.             checkFramesConsistency();
  600.             return this;

  602.         } catch (ClassNotFoundException cnfe) {
  603.             throw new RuggedException(cnfe, RuggedMessages.NOT_INTERPOLATOR_DUMP_DATA);
  604.         } catch (ClassCastException cce) {
  605.             throw new RuggedException(cce, RuggedMessages.NOT_INTERPOLATOR_DUMP_DATA);
  606.         } catch (IOException ioe) {
  607.             throw new RuggedException(ioe, RuggedMessages.NOT_INTERPOLATOR_DUMP_DATA);
  608.         }
  609.     }

  611.     /** Store frames transform interpolator.
  612.      * <p>
  613.      * This method allows to reuse the interpolator built in one instance, to build
  614.      * another instance by calling {@link #setTrajectoryAndTimeSpan(InputStream)}.
  615.      * This reduces the builder initialization time as setting up the interpolator can be long, it is
  616.      * mainly intended to be used when several runs are done (for example in an image processing chain)
  617.      * with the same configuration.
  618.      * </p>
  619.      * <p>
  620.      * This method must be called <em>after</em> both the ellipsoid and trajectory have been set.
  621.      * </p>
  622.      * @param storageStream stream where to store the interpolator
  623.      * (caller opened it and remains responsible for closing it)
  624.      * @see #setEllipsoid(EllipsoidId, BodyRotatingFrameId)
  625.      * @see #setEllipsoid(OneAxisEllipsoid)
  626.      * @see #setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  627.      * @see #setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter)
  628.      * @see #setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)
  629.      * @see #setTrajectoryAndTimeSpan(InputStream)
  630.      */
  631.     public void storeInterpolator(final OutputStream storageStream) {
  632.         try {
  633.             createInterpolatorIfNeeded();
  634.             new ObjectOutputStream(storageStream).writeObject(scToBody);
  635.         } catch (IOException ioe) {
  636.             throw new RuggedException(ioe, LocalizedCoreFormats.SIMPLE_MESSAGE, ioe.getMessage());
  637.         }
  638.     }

  640.     /** Check frames consistency.
  641.      */
  642.     private void checkFramesConsistency() {
  643.         if (ellipsoid != null && scToBody != null &&
  644.             !ellipsoid.getBodyFrame().getName().equals(scToBody.getBodyFrame().getName())) {
  645.             // if frames have been set both by direct calls and by deserializing an interpolator dump and a mismatch occurs
  646.             throw new RuggedException(RuggedMessages.FRAMES_MISMATCH_WITH_INTERPOLATOR_DUMP,
  647.                                       ellipsoid.getBodyFrame().getName(), scToBody.getBodyFrame().getName());
  648.         }
  649.     }

  651.     /** Create a transform interpolator if needed.
  652.      */
  653.     private void createInterpolatorIfNeeded() {

  655.         if (ellipsoid == null) {
  656.             throw new RuggedException(RuggedMessages.UNINITIALIZED_CONTEXT, "RuggedBuilder.setEllipsoid()");
  657.         }

  659.         if (scToBody == null) {
  660.             if (pvSample != null) {
  661.                 scToBody = createInterpolator(inertial, ellipsoid.getBodyFrame(),
  662.                                               minDate, maxDate, tStep, overshootTolerance,
  663.                                               pvSample, pvNeighborsSize, pvDerivatives,
  664.                                               aSample, aNeighborsSize, aDerivatives);
  665.             } else if (pvaPropagator != null) {
  666.                 scToBody = createInterpolator(inertial, ellipsoid.getBodyFrame(),
  667.                                               minDate, maxDate, tStep, overshootTolerance,
  668.                                               iStep, iN, pvDerivatives, aDerivatives, pvaPropagator);
  669.             } else {
  670.                 throw new RuggedException(RuggedMessages.UNINITIALIZED_CONTEXT, "RuggedBuilder.setTrajectory()");
  671.             }
  672.         }
  673.     }

  675.     /** Create a transform interpolator from positions and quaternions lists.
  676.      * @param inertialFrame inertial frame
  677.      * @param bodyFrame observed body frame
  678.      * @param minDate start of search time span
  679.      * @param maxDate end of search time span
  680.      * @param tStep step to use for inertial frame to body frame transforms cache computations
  681.      * @param overshootTolerance tolerance in seconds allowed for {@code minDate} and {@code maxDate} overshooting
  682.      * @param positionsVelocities satellite position and velocity
  683.      * @param pvInterpolationNumber number of points to use for position/velocity interpolation
  684.      * @param pvFilter filter for derivatives from the sample to use in position/velocity interpolation
  685.      * @param quaternions satellite quaternions
  686.      * @param aInterpolationNumber number of points to use for attitude interpolation
  687.      * @param aFilter filter for derivatives from the sample to use in attitude interpolation
  688.      * @return transforms interpolator
  689.      */
  690.     private static SpacecraftToObservedBody createInterpolator(final Frame inertialFrame, final Frame bodyFrame,
  691.                                                                final AbsoluteDate minDate, final AbsoluteDate maxDate,
  692.                                                                final double tStep, final double overshootTolerance,
  693.                                                                final List<TimeStampedPVCoordinates> positionsVelocities,
  694.                                                                final int pvInterpolationNumber,
  695.                                                                final CartesianDerivativesFilter pvFilter,
  696.                                                                final List<TimeStampedAngularCoordinates> quaternions,
  697.                                                                final int aInterpolationNumber,
  698.                                                                final AngularDerivativesFilter aFilter) {

  700.         return new SpacecraftToObservedBody(inertialFrame, bodyFrame,
  701.                                             minDate, maxDate, tStep, overshootTolerance,
  702.                                             positionsVelocities, pvInterpolationNumber,
  703.                                             pvFilter, quaternions, aInterpolationNumber,
  704.                                             aFilter);
  705.     }

  707.     /** Create a transform interpolator from a propagator.
  708.      * @param inertialFrame inertial frame
  709.      * @param bodyFrame observed body frame
  710.      * @param minDate start of search time span
  711.      * @param maxDate end of search time span
  712.      * @param tStep step to use for inertial frame to body frame transforms cache computations
  713.      * @param overshootTolerance tolerance in seconds allowed for {@code minDate} and {@code maxDate} overshooting
  714.      * @param interpolationStep step to use for inertial/Earth/spacecraft transforms interpolations
  715.      * @param interpolationNumber number of points of to use for inertial/Earth/spacecraft transforms interpolations
  716.      * @param pvFilter filter for derivatives from the sample to use in position/velocity interpolation
  717.      * @param aFilter filter for derivatives from the sample to use in attitude interpolation
  718.      * @param propagator global propagator
  719.      * @return transforms interpolator
  720.      */
  721.     private static SpacecraftToObservedBody createInterpolator(final Frame inertialFrame, final Frame bodyFrame,
  722.                                                                final AbsoluteDate minDate, final AbsoluteDate maxDate,
  723.                                                                final double tStep, final double overshootTolerance,
  724.                                                                final double interpolationStep, final int interpolationNumber,
  725.                                                                final CartesianDerivativesFilter pvFilter,
  726.                                                                final AngularDerivativesFilter aFilter,
  727.                                                                final Propagator propagator) {

  729.         // extract position/attitude samples from propagator
  730.         final List<TimeStampedPVCoordinates> positionsVelocities =
  731.                 new ArrayList<>();
  732.         final List<TimeStampedAngularCoordinates> quaternions =
  733.                 new ArrayList<>();
  734.         propagator.getMultiplexer().add(interpolationStep,
  735.             currentState -> {
  736.                 final AbsoluteDate  date = currentState.getDate();
  737.                 final PVCoordinates pv   = currentState.getPVCoordinates(inertialFrame);
  738.                 final Rotation      q    = currentState.getAttitude().getRotation();
  739.                 positionsVelocities.add(new TimeStampedPVCoordinates(date, pv.getPosition(), pv.getVelocity(), Vector3D.ZERO));
  740.                 quaternions.add(new TimeStampedAngularCoordinates(date, q, Vector3D.ZERO, Vector3D.ZERO));
  741.             });
  742.         propagator.propagate(minDate.shiftedBy(-interpolationStep), maxDate.shiftedBy(interpolationStep));

  744.         // orbit/attitude to body converter
  745.         return createInterpolator(inertialFrame, bodyFrame,
  746.                 minDate, maxDate, tStep, overshootTolerance,
  747.                 positionsVelocities, interpolationNumber,
  748.                 pvFilter, quaternions, interpolationNumber,
  749.                 aFilter);
  750.     }

  752.     /** Set flag for light time correction.
  753.      * <p>
  754.      * This methods set the flag for compensating or not light time between
  755.      * ground and spacecraft. Compensating this delay improves location
  756.      * accuracy and is <em>enabled</em> by default (i.e. not calling this
  757.      * method before building is therefore equivalent to calling it with
  758.      * a parameter set to {@code true}). Not compensating it is mainly useful
  759.      * for validation purposes against system that do not compensate it.
  760.      * </p>
  761.      * @param newLightTimeCorrection if true, the light travel time between ground
  762.      * and spacecraft is compensated for more accurate location
  763.      * @return the builder instance
  764.      * @see #setAberrationOfLightCorrection(boolean)
  765.      * @see #getLightTimeCorrection()
  766.      */
  767.     public RuggedBuilder setLightTimeCorrection(final boolean newLightTimeCorrection) {
  768.         this.lightTimeCorrection = newLightTimeCorrection;
  769.         return this;
  770.     }

  772.     /** Get the light time correction flag.
  773.      * @return light time correction flag
  774.      * @see #setLightTimeCorrection(boolean)
  775.      */
  776.     public boolean getLightTimeCorrection() {
  777.         return lightTimeCorrection;
  778.     }

  780.     /** Set flag for aberration of light correction.
  781.      * <p>
  782.      * This methods set the flag for compensating or not aberration of light,
  783.      * which is velocity composition between light and spacecraft when the
  784.      * light from ground points reaches the sensor.
  785.      * Compensating this velocity composition improves location
  786.      * accuracy and is <em>enabled</em> by default (i.e. not calling this
  787.      * method before building is therefore equivalent to calling it with
  788.      * a parameter set to {@code true}). Not compensating it is useful
  789.      * in two cases: for validation purposes against system that do not
  790.      * compensate it or when the pixels line of sight already include the
  791.      * correction.
  792.      * </p>
  793.      * @param newAberrationOfLightCorrection if true, the aberration of light
  794.      * is corrected for more accurate location
  795.      * @return the builder instance
  796.      * @see #setLightTimeCorrection(boolean)
  797.      * @see #getAberrationOfLightCorrection()
  798.      */
  799.     public RuggedBuilder setAberrationOfLightCorrection(final boolean newAberrationOfLightCorrection) {
  800.         this.aberrationOfLightCorrection = newAberrationOfLightCorrection;
  801.         return this;
  802.     }

  804.     /** Get the aberration of light correction flag.
  805.      * @return aberration of light correction flag
  806.      * @see #setAberrationOfLightCorrection(boolean)
  807.      */
  808.     public boolean getAberrationOfLightCorrection() {
  809.         return aberrationOfLightCorrection;
  810.     }

  812.     /** Set atmospheric refraction for line of sight correction.
  813.      * <p>
  814.      * This method sets an atmospheric refraction model to be used between
  815.      * spacecraft and ground for the correction of intersected points on ground.
  816.      * Compensating for the effect of atmospheric refraction improves location
  817.      * accuracy.
  818.      * </p>
  819.      * @param newAtmosphericRefraction the atmospheric refraction model to be used for more accurate location
  820.      * @return the builder instance
  821.      * @see #getRefractionCorrection()
  822.      */
  823.     public RuggedBuilder setRefractionCorrection(final AtmosphericRefraction newAtmosphericRefraction) {
  824.         this.atmosphericRefraction = newAtmosphericRefraction;
  825.         return this;
  826.     }

  828.     /** Get the atmospheric refraction model.
  829.      * @return atmospheric refraction model
  830.      * @see #setRefractionCorrection(AtmosphericRefraction)
  831.      */
  832.     public AtmosphericRefraction getRefractionCorrection() {
  833.         return atmosphericRefraction;
  834.     }

  836.     /** Set up line sensor model.
  837.      * @param lineSensor line sensor model
  838.      * @return the builder instance
  839.      */
  840.     public RuggedBuilder addLineSensor(final LineSensor lineSensor) {
  841.         sensors.add(lineSensor);
  842.         return this;
  843.     }

  845.     /** Remove all line sensors.
  846.      * @return the builder instance
  847.      */
  848.     public RuggedBuilder clearLineSensors() {
  849.         sensors.clear();
  850.         return this;
  851.     }

  853.     /** Get all line sensors.
  854.      * @return all line sensors (in an unmodifiable list)
  855.      */
  856.     public List<LineSensor> getLineSensors() {
  857.         return Collections.unmodifiableList(sensors);
  858.     }

  860.     /** Select inertial frame.
  861.      * @param inertialFrameId inertial frame identifier
  862.      * @return inertial frame
  863.      */
  864.     private static Frame selectInertialFrame(final InertialFrameId inertialFrameId) {

  866.         // set up the inertial frame
  867.         switch (inertialFrameId) {
  868.             case GCRF :
  869.                 return FramesFactory.getGCRF();
  870.             case EME2000 :
  871.                 return FramesFactory.getEME2000();
  872.             case MOD :
  873.                 return FramesFactory.getMOD(IERSConventions.IERS_1996);
  874.             case TOD :
  875.                 return FramesFactory.getTOD(IERSConventions.IERS_1996, true);
  876.             case VEIS1950 :
  877.                 return FramesFactory.getVeis1950();
  878.             default :
  879.                 // this should never happen
  880.                 throw new RuggedInternalError(null);
  881.         }
  882.     }

  884.     /** Select body rotating frame.
  885.      * @param bodyRotatingFrame body rotating frame identifier
  886.      * @return body rotating frame
  887.      */
  888.     private static Frame selectBodyRotatingFrame(final BodyRotatingFrameId bodyRotatingFrame) {

  890.         // set up the rotating frame
  891.         switch (bodyRotatingFrame) {
  892.             case ITRF :
  893.                 return FramesFactory.getITRF(IERSConventions.IERS_2010, true);
  894.             case ITRF_EQUINOX :
  895.                 return FramesFactory.getITRFEquinox(IERSConventions.IERS_1996, true);
  896.             case GTOD :
  897.                 return FramesFactory.getGTOD(IERSConventions.IERS_1996, true);
  898.             default :
  899.                 // this should never happen
  900.                 throw new RuggedInternalError(null);
  901.         }
  902.     }

  904.     /** Select ellipsoid.
  905.      * @param ellipsoidID reference ellipsoid identifier
  906.      * @param bodyFrame body rotating frame
  907.      * @return selected ellipsoid
  908.      */
  909.     private static OneAxisEllipsoid selectEllipsoid(final EllipsoidId ellipsoidID, final Frame bodyFrame) {

  911.         // set up the ellipsoid
  912.         switch (ellipsoidID) {
  913.             case GRS80 :
  914.                 return new OneAxisEllipsoid(Constants.GRS80_EARTH_EQUATORIAL_RADIUS,
  915.                                             Constants.GRS80_EARTH_FLATTENING,
  916.                                             bodyFrame);
  917.             case WGS84 :
  918.                 return new OneAxisEllipsoid(Constants.WGS84_EARTH_EQUATORIAL_RADIUS,
  919.                                             Constants.WGS84_EARTH_FLATTENING,
  920.                                             bodyFrame);
  921.             case IERS96 :
  922.                 return new OneAxisEllipsoid(Constants.IERS96_EARTH_EQUATORIAL_RADIUS,
  923.                                             Constants.IERS96_EARTH_FLATTENING,
  924.                                             bodyFrame);
  925.             case IERS2003 :
  926.                 return new OneAxisEllipsoid(Constants.IERS2003_EARTH_EQUATORIAL_RADIUS,
  927.                                             Constants.IERS2003_EARTH_FLATTENING,
  928.                                             bodyFrame);
  929.             default :
  930.                 // this should never happen
  931.                 throw new RuggedInternalError(null);
  932.         }

  934.     }

  936.     /** Create DEM intersection algorithm.
  937.      * @param algorithmID intersection algorithm identifier
  938.      * @param updater updater used to load Digital Elevation Model tiles
  939.      * @param maxCachedTiles maximum number of tiles stored in the cache
  940.      * @param constantElevation constant elevation over ellipsoid
  941.      * @return selected algorithm
  942.      */
  943.     private static IntersectionAlgorithm createAlgorithm(final AlgorithmId algorithmID,
  944.                                                          final TileUpdater updater, final int maxCachedTiles,
  945.                                                          final double constantElevation) {

  947.         // set up the algorithm
  948.         switch (algorithmID) {
  949.             case DUVENHAGE :
  950.                 return new DuvenhageAlgorithm(updater, maxCachedTiles, false);
  951.             case DUVENHAGE_FLAT_BODY :
  952.                 return new DuvenhageAlgorithm(updater, maxCachedTiles, true);
  953.             case BASIC_SLOW_EXHAUSTIVE_SCAN_FOR_TESTS_ONLY :
  954.                 return new BasicScanAlgorithm(updater, maxCachedTiles);
  955.             case CONSTANT_ELEVATION_OVER_ELLIPSOID :
  956.                 return new ConstantElevationAlgorithm(constantElevation);
  957.             case IGNORE_DEM_USE_ELLIPSOID :
  958.                 return new IgnoreDEMAlgorithm();
  959.             default :
  960.                 // this should never happen
  961.                 throw new RuggedInternalError(null);
  962.         }
  963.     }

  965.     /** Build a {@link Rugged} instance.
  966.      * @return built instance
  967.      */
  968.     public Rugged build() {

  970.         if (algorithmID == null) {
  971.             throw new RuggedException(RuggedMessages.UNINITIALIZED_CONTEXT, "RuggedBuilder.setAlgorithmID()");
  972.         }
  973.         if (algorithmID == AlgorithmId.CONSTANT_ELEVATION_OVER_ELLIPSOID) {
  974.             if (Double.isNaN(constantElevation)) {
  975.                 throw new RuggedException(RuggedMessages.UNINITIALIZED_CONTEXT, "RuggedBuilder.setConstantElevation()");
  976.             }
  977.         } else if (algorithmID != AlgorithmId.IGNORE_DEM_USE_ELLIPSOID) {
  978.             if (tileUpdater == null) {
  979.                 throw new RuggedException(RuggedMessages.UNINITIALIZED_CONTEXT, "RuggedBuilder.setDigitalElevationModel()");
  980.             }
  981.         }
  982.         createInterpolatorIfNeeded();
  983.         return new Rugged(createAlgorithm(algorithmID, tileUpdater, maxCachedTiles, constantElevation), ellipsoid,
  984.                           lightTimeCorrection, aberrationOfLightCorrection, atmosphericRefraction, scToBody, sensors, name);
  985.     }
  986. }
Created with JaCoCo 0.8.7.202105040129