TopocentricFrame.java

  1. /* Copyright 2002-2018 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (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.frames;

  19. import org.hipparchus.analysis.UnivariateFunction;
  20. import org.hipparchus.analysis.solvers.BracketingNthOrderBrentSolver;
  21. import org.hipparchus.analysis.solvers.UnivariateSolver;
  22. import org.hipparchus.exception.MathRuntimeException;
  23. import org.hipparchus.geometry.euclidean.threed.Rotation;
  24. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  25. import org.hipparchus.util.FastMath;
  26. import org.hipparchus.util.MathUtils;
  27. import org.orekit.bodies.BodyShape;
  28. import org.orekit.bodies.GeodeticPoint;
  29. import org.orekit.errors.OrekitException;
  30. import org.orekit.errors.OrekitExceptionWrapper;
  31. import org.orekit.time.AbsoluteDate;
  32. import org.orekit.utils.Constants;
  33. import org.orekit.utils.PVCoordinates;
  34. import org.orekit.utils.PVCoordinatesProvider;
  35. import org.orekit.utils.TimeStampedPVCoordinates;


  38. /** Topocentric frame.
  39.  * <p>Frame associated to a position near the surface of a body shape.</p>
  40.  * <p>
  41.  * The origin of the frame is at the defining {@link GeodeticPoint geodetic point}
  42.  * location, and the right-handed canonical trihedra is:
  43.  * </p>
  44.  * <ul>
  45.  *   <li>X axis in the local horizontal plane (normal to zenith direction) and
  46.  *   following the local parallel towards East</li>
  47.  *   <li>Y axis in the horizontal plane (normal to zenith direction) and
  48.  *   following the local meridian towards North</li>
  49.  *   <li>Z axis towards Zenith direction</li>
  50.  * </ul>
  51.  * @author V&eacute;ronique Pommier-Maurussane
  52.  */
  53. public class TopocentricFrame extends Frame implements PVCoordinatesProvider {

  55.     /** Serializable UID. */
  56.     private static final long serialVersionUID = -5997915708080966466L;

  58.     /** Body shape on which the local point is defined. */
  59.     private final BodyShape parentShape;

  61.     /** Point where the topocentric frame is defined. */
  62.     private final GeodeticPoint point;

  64.     /** Simple constructor.
  65.      * @param parentShape body shape on which the local point is defined
  66.      * @param point local surface point where topocentric frame is defined
  67.      * @param name the string representation
  68.      */
  69.     public TopocentricFrame(final BodyShape parentShape, final GeodeticPoint point,
  70.                             final String name) {

  72.         super(parentShape.getBodyFrame(),
  73.               new Transform(AbsoluteDate.J2000_EPOCH,
  74.                             new Transform(AbsoluteDate.J2000_EPOCH,
  75.                                           parentShape.transform(point).negate()),
  76.                             new Transform(AbsoluteDate.J2000_EPOCH,
  77.                                           new Rotation(point.getEast(), point.getZenith(),
  78.                                                        Vector3D.PLUS_I, Vector3D.PLUS_K),
  79.                                           Vector3D.ZERO)),
  80.               name, false);
  81.         this.parentShape = parentShape;
  82.         this.point = point;
  83.     }

  85.     /** Get the body shape on which the local point is defined.
  86.      * @return body shape on which the local point is defined
  87.      */
  88.     public BodyShape getParentShape() {
  89.         return parentShape;
  90.     }

  92.     /** Get the surface point defining the origin of the frame.
  93.      * @return surface point defining the origin of the frame
  94.      */
  95.     public GeodeticPoint getPoint() {
  96.         return point;
  97.     }

  99.     /** Get the zenith direction of topocentric frame, expressed in parent shape frame.
  100.      * <p>The zenith direction is defined as the normal to local horizontal plane.</p>
  101.      * @return unit vector in the zenith direction
  102.      * @see #getNadir()
  103.      */
  104.     public Vector3D getZenith() {
  105.         return point.getZenith();
  106.     }

  108.     /** Get the nadir direction of topocentric frame, expressed in parent shape frame.
  109.      * <p>The nadir direction is the opposite of zenith direction.</p>
  110.      * @return unit vector in the nadir direction
  111.      * @see #getZenith()
  112.      */
  113.     public Vector3D getNadir() {
  114.         return point.getNadir();
  115.     }

  117.    /** Get the north direction of topocentric frame, expressed in parent shape frame.
  118.      * <p>The north direction is defined in the horizontal plane
  119.      * (normal to zenith direction) and following the local meridian.</p>
  120.      * @return unit vector in the north direction
  121.      * @see #getSouth()
  122.      */
  123.     public Vector3D getNorth() {
  124.         return point.getNorth();
  125.     }

  127.     /** Get the south direction of topocentric frame, expressed in parent shape frame.
  128.      * <p>The south direction is the opposite of north direction.</p>
  129.      * @return unit vector in the south direction
  130.      * @see #getNorth()
  131.      */
  132.     public Vector3D getSouth() {
  133.         return point.getSouth();
  134.     }

  136.     /** Get the east direction of topocentric frame, expressed in parent shape frame.
  137.      * <p>The east direction is defined in the horizontal plane
  138.      * in order to complete direct triangle (east, north, zenith).</p>
  139.      * @return unit vector in the east direction
  140.      * @see #getWest()
  141.      */
  142.     public Vector3D getEast() {
  143.         return point.getEast();
  144.     }

  146.     /** Get the west direction of topocentric frame, expressed in parent shape frame.
  147.      * <p>The west direction is the opposite of east direction.</p>
  148.      * @return unit vector in the west direction
  149.      * @see #getEast()
  150.      */
  151.     public Vector3D getWest() {
  152.         return point.getWest();
  153.     }

  155.     /** Get the elevation of a point with regards to the local point.
  156.      * <p>The elevation is the angle between the local horizontal and
  157.      * the direction from local point to given point.</p>
  158.      * @param extPoint point for which elevation shall be computed
  159.      * @param frame frame in which the point is defined
  160.      * @param date computation date
  161.      * @return elevation of the point
  162.      * @exception OrekitException if frames transformations cannot be computed
  163.      */
  164.     public double getElevation(final Vector3D extPoint, final Frame frame,
  165.                                final AbsoluteDate date)
  166.         throws OrekitException {

  168.         // Transform given point from given frame to topocentric frame
  169.         final Transform t = frame.getTransformTo(this, date);
  170.         final Vector3D extPointTopo = t.transformPosition(extPoint);

  172.         // Elevation angle is PI/2 - angle between zenith and given point direction
  173.         return extPointTopo.getDelta();
  174.     }

  176.     /** Get the azimuth of a point with regards to the topocentric frame center point.
  177.      * <p>The azimuth is the angle between the North direction at local point and
  178.      * the projection in local horizontal plane of the direction from local point
  179.      * to given point. Azimuth angles are counted clockwise, i.e positive towards the East.</p>
  180.      * @param extPoint point for which elevation shall be computed
  181.      * @param frame frame in which the point is defined
  182.      * @param date computation date
  183.      * @return azimuth of the point
  184.      * @exception OrekitException if frames transformations cannot be computed
  185.      */
  186.     public double getAzimuth(final Vector3D extPoint, final Frame frame,
  187.                              final AbsoluteDate date)
  188.         throws OrekitException {

  190.         // Transform given point from given frame to topocentric frame
  191.         final Transform t = getTransformTo(frame, date).getInverse();
  192.         final Vector3D extPointTopo = t.transformPosition(extPoint);

  194.         // Compute azimuth
  195.         double azimuth = FastMath.atan2(extPointTopo.getX(), extPointTopo.getY());
  196.         if (azimuth < 0.) {
  197.             azimuth += MathUtils.TWO_PI;
  198.         }
  199.         return azimuth;

  201.     }

  203.     /** Get the range of a point with regards to the topocentric frame center point.
  204.      * @param extPoint point for which range shall be computed
  205.      * @param frame frame in which the point is defined
  206.      * @param date computation date
  207.      * @return range (distance) of the point
  208.      * @exception OrekitException if frames transformations cannot be computed
  209.      */
  210.     public double getRange(final Vector3D extPoint, final Frame frame,
  211.                            final AbsoluteDate date)
  212.         throws OrekitException {

  214.         // Transform given point from given frame to topocentric frame
  215.         final Transform t = frame.getTransformTo(this, date);
  216.         final Vector3D extPointTopo = t.transformPosition(extPoint);

  218.         // Compute range
  219.         return extPointTopo.getNorm();

  221.     }

  223.     /** Get the range rate of a point with regards to the topocentric frame center point.
  224.      * @param extPV point/velocity for which range rate shall be computed
  225.      * @param frame frame in which the point is defined
  226.      * @param date computation date
  227.      * @return range rate of the point (positive if point departs from frame)
  228.      * @exception OrekitException if frames transformations cannot be computed
  229.      */
  230.     public double getRangeRate(final PVCoordinates extPV, final Frame frame,
  231.                                final AbsoluteDate date)
  232.         throws OrekitException {

  234.         // Transform given point from given frame to topocentric frame
  235.         final Transform t = frame.getTransformTo(this, date);
  236.         final PVCoordinates extPVTopo = t.transformPVCoordinates(extPV);

  238.         // Compute range rate (doppler) : relative rate along the line of sight
  239.         return Vector3D.dotProduct(extPVTopo.getPosition(), extPVTopo.getVelocity()) /
  240.                extPVTopo.getPosition().getNorm();

  242.     }

  244.     /**
  245.      * Compute the limit visibility point for a satellite in a given direction.
  246.      * <p>
  247.      * This method can be used to compute visibility circles around ground stations
  248.      * for example, using a simple loop on azimuth, with either a fixed elevation
  249.      * or an elevation that depends on azimuth to take ground masks into account.
  250.      * </p>
  251.      * @param radius satellite distance to Earth center
  252.      * @param azimuth pointing azimuth from station
  253.      * @param elevation pointing elevation from station
  254.      * @return limit visibility point for the satellite
  255.      * @throws OrekitException if point cannot be found
  256.      */
  257.     public GeodeticPoint computeLimitVisibilityPoint(final double radius,
  258.                                                      final double azimuth, final double elevation)
  259.         throws OrekitException {
  260.         try {
  261.             // convergence threshold on point position: 1mm
  262.             final double deltaP = 0.001;
  263.             final UnivariateSolver solver =
  264.                     new BracketingNthOrderBrentSolver(deltaP / Constants.WGS84_EARTH_EQUATORIAL_RADIUS,
  265.                                                       deltaP, deltaP, 5);

  267.             // find the distance such that a point in the specified direction and at the solved-for
  268.             // distance is exactly at the specified radius
  269.             final double distance = solver.solve(1000, new UnivariateFunction() {
  270.                 /** {@inheritDoc} */
  271.                 public double value(final double x) {
  272.                     try {
  273.                         final GeodeticPoint gp = pointAtDistance(azimuth, elevation, x);
  274.                         return parentShape.transform(gp).getNorm() - radius;
  275.                     } catch (OrekitException oe) {
  276.                         throw new OrekitExceptionWrapper(oe);
  277.                     }
  278.                 }
  279.             }, 0, 2 * radius);

  281.             // return the limit point
  282.             return pointAtDistance(azimuth, elevation, distance);

  284.         } catch (MathRuntimeException mrte) {
  285.             throw new OrekitException(mrte);
  286.         } catch (OrekitExceptionWrapper lwe) {
  287.             throw lwe.getException();
  288.         }
  289.     }

  291.     /** Compute the point observed from the station at some specified distance.
  292.      * @param azimuth pointing azimuth from station
  293.      * @param elevation pointing elevation from station
  294.      * @param distance distance to station
  295.      * @return observed point
  296.      * @exception OrekitException if point cannot be computed
  297.      */
  298.     public GeodeticPoint pointAtDistance(final double azimuth, final double elevation,
  299.                                          final double distance)
  300.         throws OrekitException {
  301.         final double cosAz = FastMath.cos(azimuth);
  302.         final double sinAz = FastMath.sin(azimuth);
  303.         final double cosEl = FastMath.cos(elevation);
  304.         final double sinEl = FastMath.sin(elevation);
  305.         final Vector3D  observed = new Vector3D(distance * cosEl * sinAz,
  306.                                                 distance * cosEl * cosAz,
  307.                                                 distance * sinEl);
  308.         return parentShape.transform(observed, this, AbsoluteDate.J2000_EPOCH);
  309.     }

  311.     /** Get the {@link PVCoordinates} of the topocentric frame origin in the selected frame.
  312.      * @param date current date
  313.      * @param frame the frame where to define the position
  314.      * @return position/velocity of the topocentric frame origin (m and m/s)
  315.      * @exception OrekitException if position cannot be computed in given frame
  316.      */
  317.     public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate date, final Frame frame)
  318.         throws OrekitException {
  319.         return getTransformTo(frame, date).transformPVCoordinates(new TimeStampedPVCoordinates(date,
  320.                                                                                                Vector3D.ZERO,
  321.                                                                                                Vector3D.ZERO,
  322.                                                                                                Vector3D.ZERO));
  323.     }

  325. }
Created with JaCoCo 0.7.9.201702052155