1 /* Contributed in the public domain.
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.files.ccsds.definitions;
18
19 import org.orekit.errors.OrekitException;
20 import org.orekit.files.general.EphemerisFile.EphemerisSegment;
21 import org.orekit.frames.Frame;
22 import org.orekit.frames.Frames;
23 import org.orekit.time.AbsoluteDate;
24
25 /**
26 * An interface for creating an Orekit {@link Frame} from the specification in a CCSDS NDM
27 * file. Note that CCSDS uses "frame" to mean only orientation, while Orekit uses "frame"
28 * to mean origin and orientation. Some NDM files provide different information, so there
29 * are several methods in the interface:
30 *
31 * <ul>
32 * <li>{@link #buildCcsdsFrame(FrameFacade, AbsoluteDate)} for when only an
33 * orientation is provided. E.g. covariance section of an OEM.
34 * <li>{@link #buildCcsdsFrame(BodyFacade, FrameFacade, AbsoluteDate)} for when a
35 * center and orientation are provided. E.g. in the trajectory section of an OEM.
36 * </ul>
37 *
38 * <p>Notes for implementors: Orekit will shortcut frame transformations if frames are
39 * {@code ==}. So for best performance, memoize created frames, similar to how {@link
40 * Frames} is implemented. Also, {@link EphemerisSegment#getInertialFrame()} uses the
41 * closest frame ancestor by default, so it is better to do translations first, then
42 * rotations.
43 *
44 * @author Evan M. Ward
45 * @since 14.0
46 */
47 public interface CcsdsFrameMapper {
48
49 /**
50 * Create an Orekit {@link Frame} from the alignment specified in a CCSDS NDM.
51 *
52 * @param orientation the attitude of the returned frame.
53 * @param frameEpoch the epoch of the returned frame, if not intrinsic to the
54 * definition of the reference frame. May be {@code null} if not
55 * specified in the file. Many frames will ignore this value.
56 * @return a {@link Frame} with the given orientation. Never {@code null}.
57 * @throws OrekitException if a frame cannot be constructed for the given
58 * orientation.
59 * @since 14.0
60 */
61 Frame buildCcsdsFrame(FrameFacade orientation,
62 AbsoluteDate frameEpoch);
63
64 /**
65 * Create an Orekit {@link Frame} from the center, alignment, and epoch specified in a
66 * CCSDS NDM.
67 *
68 * @param center the origin of the returned frame.
69 * @param orientation the attitude of the returned frame.
70 * @param frameEpoch the epoch of the returned frame, if not intrinsic to the
71 * definition of the reference frame. May be {@code null} if not
72 * specified in the file. Many frames will ignore this value.
73 * @return a {@link Frame} with the given center and orientation. Never {@code null}.
74 * @throws OrekitException if a frame cannot be constructed for the given center and
75 * orientation.
76 * @since 14.0
77 */
78 Frame buildCcsdsFrame(BodyFacade center,
79 FrameFacade orientation,
80 AbsoluteDate frameEpoch);
81
82 }