1 /* Copyright 2025-2026 Hawkeye 360 (HE360)
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.estimation.measurements;
18
19 import java.util.HashMap;
20 import java.util.List;
21 import java.util.Map;
22
23 import org.hipparchus.analysis.differentiation.Gradient;
24 import org.hipparchus.analysis.differentiation.GradientField;
25 import org.orekit.frames.FieldTransform;
26 import org.orekit.frames.Frame;
27 import org.orekit.frames.Transform;
28 import org.orekit.propagation.SpacecraftState;
29 import org.orekit.time.AbsoluteDate;
30 import org.orekit.time.FieldAbsoluteDate;
31 import org.orekit.time.clocks.ClockOffset;
32 import org.orekit.time.clocks.FieldClockModel;
33 import org.orekit.time.clocks.FieldClockOffset;
34 import org.orekit.utils.FieldPVCoordinatesProvider;
35 import org.orekit.utils.PVCoordinatesProvider;
36 import org.orekit.utils.drivers.ParameterDriver;
37
38 /** Abstract interface that contains those methods necessary
39 * for both space and ground-based satellite observers.
40 *
41 * @author Brianna Aubin
42 * @since 14.0
43 */
44 public interface Observer extends MeasurementParticipant {
45
46 /** Return the PVCoordinatesProvider.
47 * @return pos/vel coordinates provider
48 */
49 PVCoordinatesProvider getPVCoordinatesProvider();
50
51 /** Return the FieldPVCoordinatesProvider.
52 * @param freeParameters number of estimated parameters
53 * @param parameterIndices indices of the estimated parameters in derivatives computations, must be driver
54 * @return pos/vel coordinates provider for values with Gradient field
55 */
56 FieldPVCoordinatesProvider<Gradient> getFieldPVCoordinatesProvider(int freeParameters,
57 Map<String, Integer> parameterIndices);
58
59 /** Get the transform between offset frame and inertial frame.
60 * <p>
61 * The offset frame takes the <em>current</em> position offset,
62 * polar motion and the meridian shift into account. The frame
63 * returned is disconnected from later changes in the parameters.
64 * When the {@link ParameterDriver parameters} managing these
65 * offsets are changed, the method must be called again to retrieve
66 * a new offset frame.
67 * </p>
68 * @param inertial inertial frame to transform to
69 * @param date date of the transform
70 * @param clockOffsetAlreadyApplied if true, the specified {@code date} is as read
71 * by the ground station clock (i.e. clock offset <em>not</em> compensated), if false,
72 * the specified {@code date} was already compensated and is a physical absolute date
73 * @return transform between offset frame and inertial frame, at <em>real</em> measurement
74 * date (i.e. with clock, Earth and station offsets applied)
75 */
76 Transform getOffsetToInertial(Frame inertial, AbsoluteDate date, boolean clockOffsetAlreadyApplied);
77
78 /** Get the transform between offset frame and inertial frame with derivatives.
79 * <p>
80 * As the East and North vectors are not well defined at pole, the derivatives
81 * of these two vectors diverge to infinity as we get closer to the pole.
82 * So this method should not be used for stations less than 0.0001 degree from
83 * either poles.
84 * </p>
85 * @param inertial inertial frame to transform to
86 * @param clockDate date of the transform, clock offset and its derivatives already compensated
87 * @param freeParameters total number of free parameters in the gradient
88 * @param indices indices of the estimated parameters in derivatives computations
89 * @return transform between offset frame and inertial frame, at specified date
90 */
91 default FieldTransform<Gradient> getOffsetToInertial(final Frame inertial,
92 final AbsoluteDate clockDate,
93 final int freeParameters,
94 final Map<String, Integer> indices) {
95 // take clock offset into account
96 final Gradient offset = getFieldOffsetValue(freeParameters, indices, clockDate);
97 final FieldAbsoluteDate<Gradient> offsetCompensatedDate = new FieldAbsoluteDate<>(clockDate, offset.negate());
98
99 return getOffsetToInertial(inertial, offsetCompensatedDate, freeParameters, indices);
100 }
101
102 /** Get the transform between offset frame and inertial frame with derivatives.
103 * <p>
104 * As the East and North vectors are not well defined at pole, the derivatives
105 * of these two vectors diverge to infinity as we get closer to the pole.
106 * So this method should not be used for stations less than 0.0001 degree from
107 * either poles.
108 * </p>
109 * @param inertial inertial frame to transform to
110 * @param offsetCompensatedDate date of the transform, clock offset and its derivatives already compensated
111 * @param freeParameters total number of free parameters in the gradient
112 * @param indices indices of the estimated parameters in derivatives computations
113 * @return transform between offset frame and inertial frame, at specified date
114 */
115 FieldTransform<Gradient> getOffsetToInertial(Frame inertial, FieldAbsoluteDate<Gradient> offsetCompensatedDate,
116 int freeParameters, Map<String, Integer> indices);
117
118 /** Create a map of the free parameter values.
119 * @param states list of ObservableSatellite measurement states
120 * @param parameterDrivers list of all parameter values for the measurement
121 * @return map of the free parameter values
122 */
123 static Map<String, Integer> getParameterIndices(final SpacecraftState[] states,
124 final List<ParameterDriver> parameterDrivers) {
125
126 // measurement derivatives are computed with respect to spacecraft state in inertial frame
127 // Parameters:
128 // - 6k..6k+2 - Position of spacecraft k (counting k from 0 to nbSat-1) in inertial frame
129 // - 6k+3..6k+5 - Velocity of spacecraft k (counting k from 0 to nbSat-1) in inertial frame
130 // - 6nbSat..n - measurements parameters (clock offset, etc)
131 int nbParams = 6 * states.length;
132 final Map<String, Integer> paramIndices = new HashMap<>();
133 for (ParameterDriver measurementDriver : parameterDrivers) {
134 if (measurementDriver.isSelected()) {
135 paramIndices.put(measurementDriver.getName(), nbParams++);
136 }
137 }
138 return paramIndices;
139 }
140
141 /**
142 * Compute actual date taking into account clock offset.
143 * @param date date as registered by observer
144 * @return corrected date
145 */
146 default AbsoluteDate getCorrectedReceptionDate(final AbsoluteDate date) {
147 final ClockOffset localClock = getClockModel().getOffset(date);
148 return date.shiftedBy(-localClock.getBias());
149 }
150
151 /**
152 * Compute actual date taking into account clock offset.
153 * @param date date as registered by observer
154 * @param nbParams number of independent variables for automatic differentiation
155 * @param paramIndices mapping between parameter name and variable index
156 * @return corrected date
157 */
158 default FieldAbsoluteDate<Gradient> getCorrectedReceptionDateField(final AbsoluteDate date,
159 final int nbParams,
160 final Map<String, Integer> paramIndices) {
161 final FieldClockModel<Gradient> fieldClockModel = getFieldClockModel(nbParams, paramIndices);
162 final GradientField field = GradientField.getField(nbParams);
163 final FieldAbsoluteDate<Gradient> fieldDate = new FieldAbsoluteDate<>(field, date);
164 final FieldClockOffset<Gradient> localClock = fieldClockModel.getOffset(fieldDate);
165 return fieldDate.shiftedBy(localClock.getBias().negate());
166 }
167
168 }