0
# Event Finding and Search
1

2
Advanced search capabilities for finding geometric events such as occultations, oppositions, and user-defined conditions. These functions enable sophisticated mission planning and analysis.
3

4
## Capabilities
5

6
### Distance Events
7

8
Find times when distances meet specified conditions.
9

10
```python { .api }
11
def gfdist(target: str, abcorr: str, obsrvr: str, relate: str, refval: float, adjust: float, step: float, cnfine: SpiceCell, result: SpiceCell) -> None:
12
    """
13
    Find times when distance between observer and target satisfies condition.
14
    
15
    Parameters:
16
    - target: str, target body name
17
    - abcorr: str, aberration correction
18
    - obsrvr: str, observer body name
19
    - relate: str, relational operator ("=", "<", ">", "LOCMIN", "LOCMAX", "ABSMIN", "ABSMAX")
20
    - refval: float, reference value for comparison
21
    - adjust: float, adjustment value for absolute extrema searches
22
    - step: float, search step size in seconds
23
    - cnfine: SpiceCell, confinement window
24
    - result: SpiceCell, result window (modified in place)
25
    
26
    Returns:
27
    None (result window is modified)
28
    """
29
```
30

31
### Occultation Events
32

33
Find occultation events between celestial bodies.
34

35
```python { .api }
36
def gfoclt(occtyp: str, front: str, fshape: str, fframe: str, back: str, bshape: str, bframe: str, abcorr: str, obsrvr: str, step: float, cnfine: SpiceCell, result: SpiceCell) -> None:
37
    """
38
    Find occultation events.
39
    
40
    Parameters:
41
    - occtyp: str, occultation type ("FULL", "ANNULAR", "PARTIAL", "ANY")
42
    - front: str, front body name
43
    - fshape: str, front body shape ("POINT", "SPHERE", "ELLIPSOID")
44
    - fframe: str, front body reference frame
45
    - back: str, back body name
46
    - bshape: str, back body shape
47
    - bframe: str, back body reference frame
48
    - abcorr: str, aberration correction
49
    - obsrvr: str, observer body name
50
    - step: float, search step size in seconds
51
    - cnfine: SpiceCell, confinement window
52
    - result: SpiceCell, result window (modified in place)
53
    
54
    Returns:
55
    None (result window is modified)
56
    """
57
```
58

59
### Angular Separation Events
60

61
Find times when angular separations meet conditions.
62

63
```python { .api }
64
def gfsep(targ1: str, shape1: str, frame1: str, targ2: str, shape2: str, frame2: str, abcorr: str, obsrvr: str, relate: str, refval: float, adjust: float, step: float, cnfine: SpiceCell, result: SpiceCell) -> None:
65
    """
66
    Find times when angular separation between two targets satisfies condition.
67
    
68
    Parameters:
69
    - targ1: str, first target body name
70
    - shape1: str, first target shape
71
    - frame1: str, first target reference frame
72
    - targ2: str, second target body name
73
    - shape2: str, second target shape
74
    - frame2: str, second target reference frame
75
    - abcorr: str, aberration correction
76
    - obsrvr: str, observer body name
77
    - relate: str, relational operator
78
    - refval: float, reference value in radians
79
    - adjust: float, adjustment value
80
    - step: float, search step size
81
    - cnfine: SpiceCell, confinement window
82
    - result: SpiceCell, result window (modified in place)
83
    
84
    Returns:
85
    None (result window is modified)
86
    """
87
```
88

89
## Common Usage Patterns
90

91
### Find Mars Opposition
92
```python
93
import spiceypy as spice
94

95
spice.furnsh("metakernel.mk")
96

97
# Create time window for search (1 year)
98
start_et = spice.str2et("2023-01-01")
99
end_et = spice.str2et("2024-01-01")
100

101
# Create confinement window
102
cnfine = spice.cell_double(2)
103
spice.wninsd(start_et, end_et, cnfine)
104

105
# Search for minimum distance (opposition)
106
result = spice.cell_double(100)
107
spice.gfdist(
108
    "MARS",           # Target
109
    "LT+S",          # Aberration correction
110
    "EARTH",         # Observer
111
    "LOCMIN",        # Local minimum
112
    0.0,             # Reference value (not used for LOCMIN)
113
    86400.0,         # Adjustment (1 day)
114
    3600.0,          # Step size (1 hour)
115
    cnfine,          # Confinement window
116
    result           # Result window
117
)
118

119
# Extract results
120
for i in range(spice.wncard(result)):
121
    start, end = spice.wnfetd(result, i)
122
    print(f"Mars opposition: {spice.et2utc(start, 'C', 0)}")
123

124
spice.kclear()
125
```