Skip to main content

Frame Transform Module

space-ast1/14/26About 2 min

Frame Transform Module

Note: This document is AI-translated. For specific APIs and behaviors, please refer to the source code.

Module Overview

The Frame Transform module provides conversion functionality between various coordinate systems commonly used in astrodynamics and aerospace dynamics. This module supports precise transformations between inertial frames, fixed frames, and various intermediate reference frames, providing foundational support for orbit calculations, attitude control, and other applications.

Core Concepts

Coordinate System Definitions

The module supports the following main coordinate systems:

  • CBI (Central Body Inertial Frame)：Central body inertial frame
  • CBF (Central Body Fixed Frame)：Central body fixed frame
  • ECI (Earth Centered Inertial Frame)：Earth-centered inertial frame, which can represent ICRF or J2000 depending on configuration
  • J2000：Earth mean equatorial frame at TT 2000-01-01 12:00:00
  • MOD (Mean of Date)：Mean equatorial frame, considering precession
  • TOD (True of Date)：True equatorial frame, considering precession and nutation
  • GTOD (Greenwich True of Date)：Greenwich true equatorial frame, with XY plane as equatorial plane, positive X-axis pointing to prime meridian, rotating with Earth
    • Also known as TDR, GCR, PEF, or EFG
  • ECF (Earth Centered Fixed Frame)：Earth-centered fixed frame, considering polar motion on top of GTOD
  • ICRF (International Celestial Reference Frame)：International Celestial Reference Frame
  • CIRF (Celestial Intermediate Reference Frame)：Celestial Intermediate Reference Frame
    • The first pole (z-axis direction) is the Celestial Intermediate Pole (CIP) at a given time
    • The fundamental plane is the intermediate equator perpendicular to the CIP at that time
    • Longitude coordinate starts from the Celestial Intermediate Origin (CIO)
  • TIRF (Terrestrial Intermediate Reference Frame)：Terrestrial Intermediate Reference Frame
    • Linked to the International Terrestrial Reference Frame (ITRF) by polar motion and the positioning angle of the terrestrial intermediate origin
    • Connected to CIRF by rotating around the CIP by the Earth Rotation Angle (ERA)

Transform Types

The module provides three main types of coordinate transformation interfaces:

  1. Transform：Returns Rotation or KinematicRotation objects
  2. Matrix：Returns coordinate transformation matrices
  3. Direct Transformation：Directly converts coordinates from one reference frame to another

Some transformations also support velocity conversion, considering the angular velocity effects of rotating coordinate systems.

Main Functions

The module supports transformations between the following coordinate systems:

  • ECI ↔ ECF：Earth-centered inertial frame and Earth-centered fixed frame
  • J2000 ↔ ECF：J2000 inertial frame and Earth-centered fixed frame
  • J2000 ↔ MOD：J2000 inertial frame and mean of date frame
  • MOD ↔ TOD：Mean of date frame and true of date frame
  • TOD ↔ GTOD：True of date frame and Greenwich true of date frame
  • GTOD ↔ ECF：Greenwich true of date frame and Earth-centered fixed frame
  • ICRF ↔ ECF：International Celestial Reference Frame and Earth-centered fixed frame
  • ICRF ↔ CIRF：International Celestial Reference Frame and Celestial Intermediate Reference Frame
  • CIRF ↔ TIRF：Celestial Intermediate Reference Frame and Terrestrial Intermediate Reference Frame
  • TIRF ↔ ECF：Terrestrial Intermediate Reference Frame and Earth-centered fixed frame

Usage Examples

1. J2000 to ECF Coordinate Conversion

#include "AstCore/FrameTransform.hpp"
#include "AstCore/TimePoint.hpp"
#include "AstMath/Vector.hpp"
#include "AstUtil/Literals.hpp"
#include "AstCore/RunTime.hpp"

AST_USING_NAMESPACE
using namespace _AST literals;

int main()
{
    // 加载基础数据并初始化，需要EOP数据
    aInitialize();
    
    // 创建时间点
    TimePoint tp = TimePoint::FromUTC(2026, 1, 1, 0, 0, 0);
    
    // J2000坐标
    Vector3d vecJ2000{1000_km, 2000_km, 3000_km};
    
    // 转换到ECF坐标
    Vector3d vecECF;
    aJ2000ToECF(tp, vecJ2000, vecECF);
    
    // 输出结果
    printf("J2000坐标: %.3f m, %.3f m, %.3f m\n", vecJ2000[0], vecJ2000[1], vecJ2000[2]);
    printf("ECF坐标: %.3f m, %.3f m, %.3f m\n", vecECF[0], vecECF[1], vecECF[2]);
    
    // 清理资源
    aUninitialize();
    
    return 0;
}

2. J2000 to ECF Conversion with Velocity

#include "AstCore/FrameTransform.hpp"
#include "AstCore/TimePoint.hpp"
#include "AstMath/Vector.hpp"
#include "AstUtil/Literals.hpp"
#include "AstCore/RunTime.hpp"

AST_USING_NAMESPACE
using namespace _AST literals;

int main()
{
    // 加载基础数据并初始化，需要EOP数据
    aInitialize();
    
    // 创建时间点
    TimePoint tp = TimePoint::FromUTC(2026, 1, 1, 0, 0, 0);
    
    // J2000坐标和速度
    Vector3d vecJ2000{1000_km, 2000_km, 3000_km};
    Vector3d velJ2000{100_km/s, 200_km/s, 300_km/s};
    
    // 转换到ECF坐标和速度
    Vector3d vecECF;
    Vector3d velECF;
    aJ2000ToECF(tp, vecJ2000, velJ2000, vecECF, velECF);
    
    // 输出结果
    printf("J2000坐标: %.3f m, %.3f m, %.3f m\n", vecJ2000[0], vecJ2000[1], vecJ2000[2]);
    printf("J2000速度: %.3f m/s, %.3f m/s, %.3f m/s\n", velJ2000[0], velJ2000[1], velJ2000[2]);
    printf("ECF坐标: %.3f m, %.3f m, %.3f m\n", vecECF[0], vecECF[1], vecECF[2]);
    printf("ECF速度: %.3f m/s, %.3f m/s, %.3f m/s\n", velECF[0], velECF[1], velECF[2]);
    
    // 清理资源
    aUninitialize();
    
    return 0;
}

3. Using Transformation Matrix

#include "AstCore/FrameTransform.hpp"
#include "AstCore/TimePoint.hpp"
#include "AstMath/Vector.hpp"
#include "AstMath/Matrix.hpp"
#include "AstUtil/Literals.hpp"
#include "AstCore/RunTime.hpp"

AST_USING_NAMESPACE
using namespace _AST literals;

int main()
{
    // 加载基础数据并初始化，需要EOP数据
    aInitialize();
    
    // 创建时间点
    TimePoint tp = TimePoint::FromUTC(2026, 1, 7, 12, 0, 0);
    
    // 获取J2000到MOD的转换矩阵
    Matrix3d matrix;
    aJ2000ToMODMatrix(tp, matrix);
    
    // J2000坐标
    Vector3d vecJ2000{1000_km, 2000_km, 3000_km};
    
    // 使用矩阵转换坐标
    Vector3d vecMOD = matrix * vecJ2000;
    
    // 输出结果
    printf("J2000坐标: %.3f m, %.3f m, %.3f m\n", vecJ2000[0], vecJ2000[1], vecJ2000[2]);
    printf("转换矩阵:\n");
    printf("%.9f %.9f %.9f\n", matrix(0,0), matrix(0,1), matrix(0,2));
    printf("%.9f %.9f %.9f\n", matrix(1,0), matrix(1,1), matrix(1,2));
    printf("%.9f %.9f %.9f\n", matrix(2,0), matrix(2,1), matrix(2,2));
    printf("MOD坐标: %.3f m, %.3f m, %.3f m\n", vecMOD[0], vecMOD[1], vecMOD[2]);
    
    // 清理资源
    aUninitialize();
    
    return 0;
}

Dependencies

  • AstGlobal.h：Project global definitions
  • AstCore/TimePoint.hpp：Time point definition
  • AstMath/Vector.hpp：Vector definition
  • AstMath/Matrix.hpp：Matrix definition
  • AstMath/Rotation.hpp：Rotation definition
  • AstCore/SOFA.hpp：Astronomical algorithm library interface
  • AstCore/EOP.hpp：Earth Orientation Parameters interface

Notes

  • All angle parameters default to radians (rad)
  • Transformation accuracy depends on the precession and nutation models used
  • Polar motion correction requires EOP data support
  • Some transformation functions provide both IAU1980 and JPL DE implementations, which can be selected via aNutationMethodSet
  • More precise model selection may be required for long time span transformations

API Reference

///
/// @file      FrameTransform.hpp
/// @brief     ~
/// @details   ~
/// @author    axel
/// @date      2026-01-29
/// @copyright 版权所有 (C) 2026-present, ast项目.
///
/// ast项目（https://github.com/space-ast/ast）
/// 本项目基于 Apache 2.0 开源许可证分发。
/// 您可在遵守许可证条款的前提下使用、修改和分发本软件。
/// 许可证全文请见：
/// 
///    http://www.apache.org/licenses/LICENSE-2.0
/// 
/// 重要须知：
/// 软件按"现有状态"提供，无任何明示或暗示的担保条件。
/// 除非法律要求或书面同意，作者与贡献者不承担任何责任。
/// 使用本软件所产生的风险，需由您自行承担。

#pragma once

#include "AstGlobal.h"
#include "LocalOrbitFrame.hpp"
#include "PlanetFrame.hpp"
#include "EarthFrame.hpp"
#include "MoonFrame.hpp"
#include "InertialFrame.hpp"
#include "AxesTransform.hpp"

AST_NAMESPACE_BEGIN


/// @todo 实现通用的坐标转换函数
/// 参考orekit、GMAT的坐标系统类，还有spice的坐标转换函数
/// 实现从一个坐标系统到另一个坐标系统的转换



AST_NAMESPACE_END
SpaceAST project
Copyright © 2026 space-ast