0
# Geometry and Surface Analysis
1

2
Advanced geometric computations including surface intersections, illumination analysis, limb finding, and visibility calculations. These functions enable detailed analysis of planetary surfaces and geometric relationships.
3

4
## Capabilities
5

6
### Surface Intercept Points
7

8
Find intersections between rays and planetary surfaces.
9

10
```python { .api }
11
def sincpt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str, dref: str, dvec: ndarray) -> Tuple[ndarray, float, ndarray, bool]:
12
    """
13
    Find surface intercept point of ray with target body.
14
    
15
    Parameters:
16
    - method: str, computation method ("ELLIPSOID", "DSK/UNPRIORITIZED")
17
    - target: str, target body name
18
    - et: float, ephemeris time
19
    - fixref: str, body-fixed reference frame
20
    - abcorr: str, aberration correction
21
    - obsrvr: str, observer body name
22
    - dref: str, reference frame for direction vector
23
    - dvec: ndarray, ray direction vector
24
    
25
    Returns:
26
    Tuple[ndarray, float, ndarray, bool]: (spoint, trgepc, srfvec, found)
27
    """
28

29
def subpnt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str) -> Tuple[ndarray, float, ndarray]:
30
    """
31
    Find sub-observer point on target body.
32
    
33
    Parameters:
34
    - method: str, computation method
35
    - target: str, target body name
36
    - et: float, ephemeris time
37
    - fixref: str, body-fixed reference frame
38
    - abcorr: str, aberration correction
39
    - obsrvr: str, observer body name
40
    
41
    Returns:
42
    Tuple[ndarray, float, ndarray]: (spoint, trgepc, srfvec)
43
    """
44
```
45

46
### Illumination Analysis
47

48
Compute illumination conditions at surface points.
49

50
```python { .api }
51
def illum(target: str, et: float, abcorr: str, obsrvr: str, spoint: ndarray) -> Tuple[float, float, float]:
52
    """
53
    Compute illumination angles at surface point.
54
    
55
    Parameters:
56
    - target: str, target body name
57
    - et: float, ephemeris time
58
    - abcorr: str, aberration correction
59
    - obsrvr: str, observer body name
60
    - spoint: ndarray, surface point vector
61
    
62
    Returns:
63
    Tuple[float, float, float]: (phase, incdnc, emissn)
64
    - phase: phase angle in radians
65
    - incdnc: incidence angle in radians
66
    - emissn: emission angle in radians
67
    """
68

69
def illumf(method: str, target: str, ilusrc: str, et: float, fixref: str, abcorr: str, obsrvr: str, spoint: ndarray) -> Tuple[float, float, float, float, float]:
70
    """
71
    Compute illumination angles with specific illumination source.
72
    
73
    Parameters:
74
    - method: str, computation method
75
    - target: str, target body name
76
    - ilusrc: str, illumination source body name
77
    - et: float, ephemeris time
78
    - fixref: str, body-fixed reference frame
79
    - abcorr: str, aberration correction
80
    - obsrvr: str, observer body name
81
    - spoint: ndarray, surface point vector
82
    
83
    Returns:
84
    Tuple[float, float, float, float, float]: (trgepc, srfvec, phase, incdnc, emissn)
85
    """
86
```
87

88
### Limb and Terminator Points
89

90
Find limb and terminator points on planetary bodies.
91

92
```python { .api }
93
def limbpt(method: str, target: str, et: float, fixref: str, abcorr: str, corloc: str, obsrvr: str, refvec: ndarray, rolstp: float, ncuts: int, schstp: float, soltol: float) -> Tuple[int, ndarray, ndarray, ndarray]:
94
    """
95
    Find limb points on target body.
96
    
97
    Parameters:
98
    - method: str, computation method
99
    - target: str, target body name
100
    - et: float, ephemeris time
101
    - fixref: str, body-fixed reference frame
102
    - abcorr: str, aberration correction
103
    - corloc: str, correction location
104
    - obsrvr: str, observer body name
105
    - refvec: ndarray, reference vector
106
    - rolstp: float, roll step size
107
    - ncuts: int, number of cuts
108
    - schstp: float, search step size
109
    - soltol: float, solution tolerance
110
    
111
    Returns:
112
    Tuple[int, ndarray, ndarray, ndarray]: (npts, points, epochs, tangts)
113
    """
114
```
115

116
## Common Usage Patterns
117

118
### Find Sub-Earth Point on Mars
119
```python
120
import spiceypy as spice
121

122
spice.furnsh("metakernel.mk")
123

124
et = spice.str2et("2023-01-01T12:00:00")
125
spoint, trgepc, srfvec = spice.subpnt(
126
    "INTERCEPT/ELLIPSOID",
127
    "MARS",
128
    et,
129
    "IAU_MARS",
130
    "LT+S",
131
    "EARTH"
132
)
133

134
# Convert to lat/lon coordinates
135
radius, lon, lat = spice.reclat(spoint)
136
print(f"Sub-Earth point: lat={spice.dpr()*lat:.2f}°, lon={spice.dpr()*lon:.2f}°")
137

138
spice.kclear()
139
```