FootprintOverlapDetector.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.propagation.events;

  19. import java.util.ArrayList;
  20. import java.util.List;

  22. import org.hipparchus.geometry.enclosing.EnclosingBall;
  23. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  24. import org.hipparchus.geometry.spherical.twod.Edge;
  25. import org.hipparchus.geometry.spherical.twod.S2Point;
  26. import org.hipparchus.geometry.spherical.twod.Sphere2D;
  27. import org.hipparchus.geometry.spherical.twod.SphericalPolygonsSet;
  28. import org.hipparchus.geometry.spherical.twod.Vertex;
  29. import org.hipparchus.ode.events.Action;
  30. import org.hipparchus.util.FastMath;
  31. import org.hipparchus.util.SinCos;
  32. import org.orekit.bodies.BodyShape;
  33. import org.orekit.bodies.GeodeticPoint;
  34. import org.orekit.bodies.OneAxisEllipsoid;
  35. import org.orekit.frames.Transform;
  36. import org.orekit.geometry.fov.FieldOfView;
  37. import org.orekit.models.earth.tessellation.DivertedSingularityAiming;
  38. import org.orekit.models.earth.tessellation.EllipsoidTessellator;
  39. import org.orekit.propagation.SpacecraftState;
  40. import org.orekit.propagation.events.handlers.EventHandler;
  41. import org.orekit.propagation.events.handlers.StopOnIncreasing;

  43. /** Detector triggered by geographical region entering/leaving a spacecraft sensor
  44.  * {@link FieldOfView Field Of View}.
  45.  * <p>
  46.  * This detector is a mix between to {@link FieldOfViewDetector} and {@link
  47.  * GeographicZoneDetector}. Similar to the first detector above, it triggers events
  48.  * related to entry/exit of targets in a Field Of View, taking attitude into account.
  49.  * Similar to the second detector above, its target is an entire geographic region
  50.  * (which can even be split in several non-connected patches and can have holes).
  51.  * </p>
  52.  * <p>
  53.  * This detector is typically used for ground observation missions with agile
  54.  * satellites than can look away from nadir.
  55.  * </p>
  56.  * <p>The default implementation behavior is to {@link Action#CONTINUE continue}
  57.  * propagation at FOV entry and to {@link Action#STOP stop} propagation
  58.  * at FOV exit. This can be changed by calling
  59.  * {@link #withHandler(EventHandler)} after construction.</p>
  60.  * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
  61.  * @see FieldOfViewDetector
  62.  * @see GeographicZoneDetector
  63.  * @author Luc Maisonobe
  64.  * @since 7.1
  65.  */
  66. public class FootprintOverlapDetector extends AbstractDetector<FootprintOverlapDetector> {

  68.     /** Field of view. */
  69.     private final FieldOfView fov;

  71.     /** Body on which the geographic zone is defined. */
  72.     private final OneAxisEllipsoid body;

  74.     /** Geographic zone to consider. */
  75.     private final SphericalPolygonsSet zone;

  77.     /** Linear step used for sampling the geographic zone. */
  78.     private final double samplingStep;

  80.     /** Sampling of the geographic zone. */
  81.     private final List<SamplingPoint> sampledZone;

  83.     /** Center of the spherical cap surrounding the zone. */
  84.     private final Vector3D capCenter;

  86.     /** Cosine of the radius of the spherical cap surrounding the zone. */
  87.     private final double capCos;

  89.     /** Sine of the radius of the spherical cap surrounding the zone. */
  90.     private final double capSin;

  92.     /** Build a new instance.
  93.      * <p>The maximal interval between distance to FOV boundary checks should
  94.      * be smaller than the half duration of the minimal pass to handle,
  95.      * otherwise some short passes could be missed.</p>
  96.      * @param fov sensor field of view
  97.      * @param body body on which the geographic zone is defined
  98.      * @param zone geographic zone to consider
  99.      * @param samplingStep linear step used for sampling the geographic zone (in meters)
  100.      * @deprecated as of 10.1, replaced by {@link #FootprintOverlapDetector(FieldOfView, OneAxisEllipsoid, SphericalPolygonsSet, double)}
  101.      */
  102.     @Deprecated
  103.     public FootprintOverlapDetector(final org.orekit.propagation.events.FieldOfView fov,
  104.                                     final OneAxisEllipsoid body,
  105.                                     final SphericalPolygonsSet zone,
  106.                                     final double samplingStep) {
  107.         this(DEFAULT_MAXCHECK, DEFAULT_THRESHOLD, DEFAULT_MAX_ITER,
  108.              new StopOnIncreasing<FootprintOverlapDetector>(),
  109.              fov, body, zone, samplingStep, sample(body, zone, samplingStep));
  110.     }

  112.     /** Build a new instance.
  113.      * <p>The maximal interval between distance to FOV boundary checks should
  114.      * be smaller than the half duration of the minimal pass to handle,
  115.      * otherwise some short passes could be missed.</p>
  116.      * @param fov sensor field of view
  117.      * @param body body on which the geographic zone is defined
  118.      * @param zone geographic zone to consider
  119.      * @param samplingStep linear step used for sampling the geographic zone (in meters)
  120.      * @since 10.1
  121.      */
  122.     public FootprintOverlapDetector(final FieldOfView fov,
  123.                                     final OneAxisEllipsoid body,
  124.                                     final SphericalPolygonsSet zone,
  125.                                     final double samplingStep) {
  126.         this(DEFAULT_MAXCHECK, DEFAULT_THRESHOLD, DEFAULT_MAX_ITER,
  127.              new StopOnIncreasing<FootprintOverlapDetector>(),
  128.              fov, body, zone, samplingStep, sample(body, zone, samplingStep));
  129.     }

  131.     /** Private constructor with full parameters.
  132.      * <p>
  133.      * This constructor is private as users are expected to use the builder
  134.      * API with the various {@code withXxx()} methods to set up the instance
  135.      * in a readable manner without using a huge amount of parameters.
  136.      * </p>
  137.      * @param maxCheck maximum checking interval (s)
  138.      * @param threshold convergence threshold (s)
  139.      * @param maxIter maximum number of iterations in the event time search
  140.      * @param handler event handler to call at event occurrences
  141.      * @param body body on which the geographic zone is defined
  142.      * @param zone geographic zone to consider
  143.      * @param fov sensor field of view
  144.      * @param sampledZone sampling of the geographic zone
  145.      * @param samplingStep linear step used for sampling the geographic zone (in meters)
  146.      */
  147.     private FootprintOverlapDetector(final double maxCheck, final double threshold,
  148.                                      final int maxIter, final EventHandler<? super FootprintOverlapDetector> handler,
  149.                                      final FieldOfView fov,
  150.                                      final OneAxisEllipsoid body,
  151.                                      final SphericalPolygonsSet zone,
  152.                                      final double samplingStep,
  153.                                      final List<SamplingPoint> sampledZone) {

  155.         super(maxCheck, threshold, maxIter, handler);
  156.         this.fov          = fov;
  157.         this.body         = body;
  158.         this.samplingStep = samplingStep;
  159.         this.zone         = zone;
  160.         this.sampledZone  = sampledZone;

  162.         final EnclosingBall<Sphere2D, S2Point> cap = zone.getEnclosingCap();
  163.         final SinCos sc = FastMath.sinCos(cap.getRadius());
  164.         this.capCenter    = cap.getCenter().getVector();
  165.         this.capCos       = sc.cos();
  166.         this.capSin       = sc.sin();

  168.     }

  170.     /** Sample the region.
  171.      * @param body body on which the geographic zone is defined
  172.      * @param zone geographic zone to consider
  173.      * @param samplingStep  linear step used for sampling the geographic zone (in meters)
  174.      * @return sampling points
  175.      */
  176.     private static List<SamplingPoint> sample(final OneAxisEllipsoid body,
  177.                                               final SphericalPolygonsSet zone,
  178.                                               final double samplingStep) {

  180.         final List<SamplingPoint> sampledZone = new ArrayList<SamplingPoint>();

  182.         // sample the zone boundary
  183.         final List<Vertex> boundary = zone.getBoundaryLoops();
  184.         for (final Vertex loopStart : boundary) {
  185.             int count = 0;
  186.             for (Vertex v = loopStart; count == 0 || v != loopStart; v = v.getOutgoing().getEnd()) {
  187.                 ++count;
  188.                 final Edge edge = v.getOutgoing();
  189.                 final int n = (int) FastMath.ceil(edge.getLength() * body.getEquatorialRadius() / samplingStep);
  190.                 for (int i = 0; i < n; ++i) {
  191.                     final S2Point intermediate = new S2Point(edge.getPointAt(i * edge.getLength() / n));
  192.                     final GeodeticPoint gp = new GeodeticPoint(0.5 * FastMath.PI - intermediate.getPhi(),
  193.                                                                intermediate.getTheta(), 0.0);
  194.                     sampledZone.add(new SamplingPoint(body.transform(gp), gp.getZenith()));
  195.                 }
  196.             }
  197.         }

  199.         // sample the zone interior
  200.         final EllipsoidTessellator tessellator =
  201.                         new EllipsoidTessellator(body, new DivertedSingularityAiming(zone), 1);
  202.         final List<List<GeodeticPoint>> gpSample = tessellator.sample(zone, samplingStep, samplingStep);
  203.         for (final List<GeodeticPoint> list : gpSample) {
  204.             for (final GeodeticPoint gp : list) {
  205.                 sampledZone.add(new SamplingPoint(body.transform(gp), gp.getZenith()));
  206.             }
  207.         }

  209.         return sampledZone;

  211.     }

  213.     /** {@inheritDoc} */
  214.     @Override
  215.     protected FootprintOverlapDetector create(final double newMaxCheck, final double newThreshold,
  216.                                               final int newMaxIter,
  217.                                               final EventHandler<? super FootprintOverlapDetector> newHandler) {
  218.         return new FootprintOverlapDetector(newMaxCheck, newThreshold, newMaxIter, newHandler,
  219.                                             fov, body, zone, samplingStep, sampledZone);
  220.     }

  222.     /** Get the geographic zone triggering the events.
  223.      * <p>
  224.      * The zone is mapped on the unit sphere
  225.      * </p>
  226.      * @return geographic zone triggering the events
  227.      */
  228.     public SphericalPolygonsSet getZone() {
  229.         return zone;
  230.     }

  232.     /** Get the Field Of View.
  233.      * @return Field Of View
  234.      * @since 10.1
  235.      */
  236.     public FieldOfView getFOV() {
  237.         return fov;
  238.     }

  240.     /** Get the Field Of View.
  241.      * @return Field Of View, if detector has been built from a
  242.      * {@link org.orekit.propagation.events.FieldOfView}, or null of the
  243.      * detector was built from another implementation of {@link FieldOfView}
  244.      * @deprecated as of 10.1, replaced by {@link #getFOV()}
  245.      */
  246.     @Deprecated
  247.     public org.orekit.propagation.events.FieldOfView getFieldOfView() {
  248.         return fov instanceof org.orekit.propagation.events.FieldOfView ?
  249.                (org.orekit.propagation.events.FieldOfView) fov :
  250.                null;
  251.     }

  253.     /** Get the body on which the geographic zone is defined.
  254.      * @return body on which the geographic zone is defined
  255.      */
  256.     public BodyShape getBody() {
  257.         return body;
  258.     }

  260.     /** {@inheritDoc}
  261.      * <p>
  262.      * The g function value is the minimum offset among the region points
  263.      * with respect to the Field Of View boundary. It is positive if all region
  264.      * points are outside of the Field Of View, and negative if at least some
  265.      * of the region points are inside of the Field Of View. The minimum is
  266.      * computed by sampling the region, considering only the points for which
  267.      * the spacecraft is above the horizon. The accuracy of the detection
  268.      * depends on the linear sampling step set at detector construction. If
  269.      * the spacecraft is below horizon for all region points, an arbitrary
  270.      * positive value is returned.
  271.      * </p>
  272.      * <p>
  273.      * As per the previous definition, when the region enters the Field Of
  274.      * View, a decreasing event is generated, and when the region leaves
  275.      * the Field Of View, an increasing event is generated.
  276.      * </p>
  277.      */
  278.     public double g(final SpacecraftState s) {

  280.         // initial arbitrary positive value
  281.         double value = FastMath.PI;

  283.         // get spacecraft position in body frame
  284.         final Vector3D      scBody      = s.getPVCoordinates(body.getBodyFrame()).getPosition();

  286.         // map the point to a sphere
  287.         final GeodeticPoint gp          = body.transform(scBody, body.getBodyFrame(), s.getDate());
  288.         final S2Point       s2p         = new S2Point(gp.getLongitude(), 0.5 * FastMath.PI - gp.getLatitude());

  290.         // for faster computation, we start using only the surrounding cap, to filter out
  291.         // far away points (which correspond to most of the points if the zone is small)
  292.         final Vector3D p   = s2p.getVector();
  293.         final double   dot = Vector3D.dotProduct(p, capCenter);
  294.         if (dot < capCos) {
  295.             // the spacecraft is outside of the cap, look for the closest cap point
  296.             final Vector3D t     = p.subtract(dot, capCenter).normalize();
  297.             final Vector3D close = new Vector3D(capCos, capCenter, capSin, t);
  298.             if (Vector3D.dotProduct(p, close) < -0.01) {
  299.                 // the spacecraft is not visible from the cap edge,
  300.                 // even taking some margin into account for sphere/ellipsoid different shapes
  301.                 // this induces no points in the zone can see the spacecraft,
  302.                 // we can return the arbitrary initial positive value without performing further computation
  303.                 return value;
  304.             }
  305.         }

  307.         // the spacecraft may be visible from some points in the zone, check them all
  308.         final Transform bodyToSc = new Transform(s.getDate(),
  309.                                                  body.getBodyFrame().getTransformTo(s.getFrame(), s.getDate()),
  310.                                                  s.toTransform());
  311.         for (final SamplingPoint point : sampledZone) {
  312.             final Vector3D lineOfSightBody = point.getPosition().subtract(scBody);
  313.             if (Vector3D.dotProduct(lineOfSightBody, point.getZenith()) <= 0) {
  314.                 // spacecraft is above this sample point local horizon
  315.                 // get line of sight in spacecraft frame
  316.                 final double offset = fov.offsetFromBoundary(bodyToSc.transformVector(lineOfSightBody),
  317.                                                              0.0, VisibilityTrigger.VISIBLE_ONLY_WHEN_FULLY_IN_FOV);
  318.                 value = FastMath.min(value, offset);
  319.             }
  320.         }

  322.         return value;

  324.     }

  326.     /** Container for sampling points. */
  327.     private static class SamplingPoint {

  329.         /** Position of the point. */
  330.         private final Vector3D position;

  332.         /** Zenith vector of the point. */
  333.         private final Vector3D zenith;

  335.         /** Simple constructor.
  336.          * @param position position of the point
  337.          * @param zenith zenith vector of the point
  338.          */
  339.         SamplingPoint(final Vector3D position, final Vector3D zenith) {
  340.             this.position = position;
  341.             this.zenith   = zenith;
  342.         }

  344.         /** Get the point position.
  345.          * @return point position
  346.          */
  347.         public Vector3D getPosition() {
  348.             return position;
  349.         }

  351.         /** Get the point zenith vector.
  352.          * @return point zenith vector
  353.          */
  354.         public Vector3D getZenith() {
  355.             return zenith;
  356.         }

  358.     }

  360. }
Created with JaCoCo 0.8.6.202009150832