FieldLatitudeRangeCrossingDetector.java

  1. /* Copyright 2023-2024 Alberto Ferrero
  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.  * Alberto Ferrero 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;

  18. import org.hipparchus.CalculusFieldElement;
  19. import org.hipparchus.Field;
  20. import org.hipparchus.util.FastMath;
  21. import org.orekit.bodies.FieldGeodeticPoint;
  22. import org.orekit.bodies.OneAxisEllipsoid;
  23. import org.orekit.propagation.FieldSpacecraftState;
  24. import org.orekit.propagation.events.handlers.FieldEventHandler;
  25. import org.orekit.propagation.events.handlers.FieldStopOnIncreasing;


  26. /** Detector for geographic latitude crossing.
  27.  * <p>This detector identifies when a spacecraft crosses a fixed
  28.  * latitude range with respect to a central body.</p>
  29.  * @author Alberto Ferrero
  30.  * @since 12.0
  31.  * @param <T> type of the field elements
  32.  */
  33. public class FieldLatitudeRangeCrossingDetector <T extends CalculusFieldElement<T>>
  34.         extends FieldAbstractDetector<FieldLatitudeRangeCrossingDetector<T>, T> {

  35.     /**
  36.      * Body on which the latitude is defined.
  37.      */
  38.     private final OneAxisEllipsoid body;

  39.     /**
  40.      * Fixed latitude to be crossed, lower boundary in radians.
  41.      */
  42.     private final double fromLatitude;

  43.     /**
  44.      * Fixed latitude to be crossed, upper boundary in radians.
  45.      */
  46.     private final double toLatitude;

  47.     /**
  48.      * Sign, to get reversed inclusion latitude range (lower > upper).
  49.      */
  50.     private final double sign;

  51.     /**
  52.      * Build a new detector.
  53.      * <p>The new instance uses default values for maximal checking interval
  54.      * ({@link #DEFAULT_MAXCHECK}) and convergence threshold ({@link
  55.      * #DEFAULT_THRESHOLD}).</p>
  56.      * @param field        the type of numbers to use.
  57.      * @param body         body on which the latitude is defined
  58.      * @param fromLatitude latitude to be crossed, lower range boundary
  59.      * @param toLatitude   latitude to be crossed, upper range boundary
  60.      */
  61.     public FieldLatitudeRangeCrossingDetector(final Field<T> field,
  62.                                               final OneAxisEllipsoid body,
  63.                                               final double fromLatitude,
  64.                                               final double toLatitude) {
  65.         this(FieldAdaptableInterval.of(DEFAULT_MAXCHECK),
  66.             field.getZero().add(DEFAULT_THRESHOLD),
  67.             DEFAULT_MAX_ITER,
  68.             new FieldStopOnIncreasing<>(),
  69.             body,
  70.             fromLatitude,
  71.             toLatitude);
  72.     }

  73.     /**
  74.      * Build a detector.
  75.      *
  76.      * @param maxCheck     maximal checking interval (s)
  77.      * @param threshold    convergence threshold (s)
  78.      * @param body         body on which the latitude is defined
  79.      * @param fromLatitude latitude to be crossed, lower range boundary
  80.      * @param toLatitude   latitude to be crossed, upper range boundary
  81.      */
  82.     public FieldLatitudeRangeCrossingDetector(final T maxCheck, final T threshold,
  83.                                               final OneAxisEllipsoid body, final double fromLatitude, final double toLatitude) {
  84.         this(FieldAdaptableInterval.of(maxCheck.getReal()), threshold, DEFAULT_MAX_ITER, new FieldStopOnIncreasing<>(),
  85.             body, fromLatitude, toLatitude);
  86.     }

  87.     /**
  88.      * Private constructor with full parameters.
  89.      * <p>
  90.      * This constructor is private as users are expected to use the builder
  91.      * API with the various {@code withXxx()} methods to set up the instance
  92.      * in a readable manner without using a huge amount of parameters.
  93.      * </p>
  94.      *
  95.      * @param maxCheck     maximum checking interval (s)
  96.      * @param threshold    convergence threshold (s)
  97.      * @param maxIter      maximum number of iterations in the event time search
  98.      * @param handler      event handler to call at event occurrences
  99.      * @param body         body on which the latitude is defined
  100.      * @param fromLatitude latitude to be crossed, lower range boundary
  101.      * @param toLatitude   latitude to be crossed, upper range boundary
  102.      */
  103.     protected FieldLatitudeRangeCrossingDetector(final FieldAdaptableInterval<T> maxCheck,
  104.                                                  final T threshold,
  105.                                                  final int maxIter,
  106.                                                  final FieldEventHandler<T> handler,
  107.                                                  final OneAxisEllipsoid body,
  108.                                                  final double fromLatitude,
  109.                                                  final double toLatitude) {
  110.         super(maxCheck, threshold, maxIter, handler);
  111.         this.body = body;
  112.         this.fromLatitude = fromLatitude;
  113.         this.toLatitude = toLatitude;
  114.         this.sign = FastMath.signum(toLatitude - fromLatitude);
  115.     }

  116.     /**
  117.      * {@inheritDoc}
  118.      */
  119.     @Override
  120.     protected FieldLatitudeRangeCrossingDetector<T> create(final FieldAdaptableInterval<T> newMaxCheck,
  121.                                                            final T newThreshold,
  122.                                                            final int newMaxIter,
  123.                                                            final FieldEventHandler<T> newHandler) {
  124.         return new FieldLatitudeRangeCrossingDetector<>(newMaxCheck, newThreshold, newMaxIter, newHandler,
  125.             body, fromLatitude, toLatitude);
  126.     }

  127.     /**
  128.      * Get the body on which the geographic zone is defined.
  129.      *
  130.      * @return body on which the geographic zone is defined
  131.      */
  132.     public OneAxisEllipsoid getBody() {
  133.         return body;
  134.     }

  135.     /**
  136.      * Get the fixed latitude range to be crossed (radians), lower boundary.
  137.      *
  138.      * @return fixed lower boundary latitude range to be crossed (radians)
  139.      */
  140.     public double getFromLatitude() {
  141.         return fromLatitude;
  142.     }

  143.     /**
  144.      * Get the fixed latitude range to be crossed (radians), upper boundary.
  145.      *
  146.      * @return fixed lower boundary latitude range to be crossed (radians)
  147.      */
  148.     public double getToLatitude() {
  149.         return toLatitude;
  150.     }

  151.     /**
  152.      * Compute the value of the detection function.
  153.      * <p>
  154.      * The value is positive if the spacecraft latitude is inside the latitude range.
  155.      * It is positive if the spacecraft is northward to lower boundary range and southward to upper boundary range,
  156.      * with respect to the fixed latitude range.
  157.      * </p>
  158.      *
  159.      * @param s the current state information: date, kinematics, attitude
  160.      * @return positive if spacecraft inside the range
  161.      */
  162.     public T g(final FieldSpacecraftState<T> s) {

  163.         // convert state to geodetic coordinates
  164.         final FieldGeodeticPoint<T> gp = body.transform(s.getPVCoordinates().getPosition(),
  165.             s.getFrame(), s.getDate());

  166.         // point latitude
  167.         final T latitude = gp.getLatitude();

  168.         // inside or outside latitude range
  169.         return latitude.subtract(fromLatitude).multiply(latitude.negate().add(toLatitude)).multiply(sign);

  170.     }

  171. }