0
# Reference Frames
1

2
Functions for working with reference frames including transformations between frames, frame definitions, and orientation computations. Reference frames define coordinate system orientations and are essential for accurate space geometry calculations.
3

4
## Capabilities
5

6
### Frame Transformations
7

8
Compute transformation matrices between reference frames.
9

10
```python { .api }
11
def pxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]:
12
    """
13
    Return position transformation matrix from one frame to another.
14
    
15
    Parameters:
16
    - from_frame: str, source reference frame
17
    - to_frame: str, target reference frame  
18
    - et: Union[float, ndarray], ephemeris time(s)
19
    
20
    Returns:
21
    Union[ndarray, ndarray]: 3x3 transformation matrix or array of matrices
22
    """
23

24
def sxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]:
25
    """
26
    Return state transformation matrix from one frame to another.
27
    
28
    Parameters:
29
    - from_frame: str, source reference frame
30
    - to_frame: str, target reference frame
31
    - et: Union[float, ndarray], ephemeris time(s)
32
    
33
    Returns:
34
    Union[ndarray, ndarray]: 6x6 state transformation matrix or array of matrices
35
    """
36
```
37

38
### Frame Information
39

40
Query frame names, IDs, and properties.
41

42
```python { .api }
43
def frmnam(frcode: int) -> str:
44
    """
45
    Return frame name given frame ID code.
46
    
47
    Parameters:
48
    - frcode: int, frame ID code
49
    
50
    Returns:
51
    str: frame name
52
    """
53

54
def namfrm(frname: str) -> int:
55
    """
56
    Return frame ID code given frame name.
57
    
58
    Parameters:
59
    - frname: str, frame name
60
    
61
    Returns:
62
    int: frame ID code
63
    """
64

65
def frinfo(frcode: int) -> Tuple[int, int, int, bool]:
66
    """
67
    Return frame information.
68
    
69
    Parameters:
70
    - frcode: int, frame ID code
71
    
72
    Returns:
73
    Tuple[int, int, int, bool]: (cent, frclss, clssid, found)
74
    """
75
```
76

77
### Built-in Frame Functions
78

79
Functions for working with built-in SPICE reference frames.
80

81
```python { .api }
82
def builtin_frames() -> List[Tuple[int, str]]:
83
    """
84
    Return list of built-in reference frames.
85
    
86
    Returns:
87
    List[Tuple[int, str]]: list of (frame_id, frame_name) tuples
88
    """
89

90
def cidfrm(cent: int) -> Tuple[int, str, bool]:
91
    """
92
    Return body-fixed frame associated with an object.
93
    
94
    Parameters:
95
    - cent: int, central body ID
96
    
97
    Returns:
98
    Tuple[int, str, bool]: (frcode, frname, found)
99
    """
100
```
101

102
## Common Usage Patterns
103

104
### Basic Frame Transformation
105
```python
106
import spiceypy as spice
107

108
# Transform from J2000 to IAU_EARTH frame
109
et = spice.str2et("2023-01-01T12:00:00")
110
transform = spice.pxform("J2000", "IAU_EARTH", et)
111

112
# Apply transformation to a vector
113
vector_j2000 = [1000.0, 0.0, 0.0]  # X-axis in J2000
114
vector_earth = spice.mxv(transform, vector_j2000)
115
print(f"Vector in Earth frame: {vector_earth}")
116
```
117

118
### State Transformation
119
```python
120
# Transform state vector (position + velocity)
121
state_transform = spice.sxform("J2000", "IAU_MARS", et)
122
state_j2000 = [1000.0, 0.0, 0.0, 0.0, 1.0, 0.0]  # Example state
123
state_mars = spice.mxv(state_transform, state_j2000)
124
```