Skip to content

API reference

earthcarekit.overpass

Utilities for processing satellite overpasses relative to ground stations.

Notes

This module depends on other internal modules:

Referenced by:

OverpassInfo dataclass

Class storing details about an overpass, including duration, distance, time, closest index, etc.

Attributes:

Name Type Description
site_name str

Name of the site flown over.
site_lat_deg_north float

Latitude of the site in degrees north.
site_lon_deg_east float

Longitude of the site in degrees north.
site_radius_km float

Radius in kilometers around the site the overpass took place.
start_index int

Index at the start of the overpass.
end_index int

Index at the end of the overpass.
start_time Timestamp

Time at the start of the overpass.
end_time Timestamp

Time at the end of the overpass.
start_lat_deg_north float

Latitude at the start of the overpass.
start_lon_deg_east float

Latitude at the end of the overpass.
end_lat_deg_north float

Longitude at the start of the overpass.
end_lon_deg_east float

Longitude at the end of the overpass.
closest_index int

Index of the data sample that is geographically closest to the site.
closest_lat_deg_north float

Latitude of the data sample that is geographically closest to the site.
closest_lon_deg_east float

Longitude of the data sample that is geographically closest to the site.
closest_time Timestamp

Timestamp of the data sample that is geographically closest to the site.
closest_distance_km float

Distance in kilometers of the data sample that is geographically closest to the site.
along_track_distance_km float

Distance in kilometers along the overpass track withing the set radius.
frame_crosses_pole bool

Whether the original track crosses a pole at any point (not necessarily within the radius).
samples int

Number of data sample within the radius.
site Site

Site object.
Returned by:
Source code in earthcarekit/overpass/_overpass_info.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@dataclass
class OverpassInfo:
    """
    Class storing details about an overpass, including duration, distance, time, closest index, etc.

    Attributes:
        site_name (str): Name of the site flown over.
        site_lat_deg_north (float): Latitude of the site in degrees north.
        site_lon_deg_east (float): Longitude of the site in degrees north.
        site_radius_km (float): Radius in kilometers around the site the overpass took place.
        start_index (int): Index at the start of the overpass.
        end_index (int): Index at the end of the overpass.
        start_time (pd.Timestamp): Time at the start of the overpass.
        end_time (pd.Timestamp): Time at the end of the overpass.
        start_lat_deg_north (float): Latitude at the start of the overpass.
        start_lon_deg_east (float): Latitude at the end of the overpass.
        end_lat_deg_north (float): Longitude at the start of the overpass.
        end_lon_deg_east (float): Longitude at the end of the overpass.
        closest_index (int): Index of the data sample that is geographically closest to the site.
        closest_lat_deg_north (float): Latitude of the data sample that is geographically closest to the site.
        closest_lon_deg_east (float): Longitude of the data sample that is geographically closest to the site.
        closest_time (pd.Timestamp): Timestamp of the data sample that is geographically closest to the site.
        closest_distance_km (float): Distance in kilometers of the data sample that is geographically closest to the site.
        along_track_distance_km (float): Distance in kilometers along the overpass track withing the set radius.
        frame_crosses_pole (bool): Whether the original track crosses a pole at any point (not necessarily within the radius).
        samples (int): Number of data sample within the radius.
        site (Site): Site object.
    """

    site_name: str
    site_lat_deg_north: float
    site_lon_deg_east: float
    site_radius_km: float
    start_index: int
    end_index: int
    start_time: pd.Timestamp
    end_time: pd.Timestamp
    start_lat_deg_north: float
    start_lon_deg_east: float
    end_lat_deg_north: float
    end_lon_deg_east: float
    closest_index: int
    closest_lat_deg_north: float
    closest_lon_deg_east: float
    closest_time: pd.Timestamp
    closest_distance_km: float
    along_track_distance_km: float
    frame_crosses_pole: bool
    samples: int
    site: Site

    @property
    def site_coords(self) -> tuple[float, float]:
        """Returns lat/lon coordinates of the overpassed site or center."""
        return self.site_lat_deg_north, self.site_lon_deg_east

    @property
    def index_range(self) -> tuple[int, int]:
        """Returns start and end indecies of the overpass."""
        return self.start_index, self.end_index

    @property
    def time_range(self) -> tuple[pd.Timestamp, pd.Timestamp]:
        """Returns start and end times of the overpass."""
        return self.start_time, self.end_time

    @property
    def start_coords(self) -> tuple[float, float]:
        """Returns lat/lon coordinates of the satellite at the start of the overpass."""
        return self.start_lat_deg_north, self.start_lon_deg_east

    @property
    def end_coords(self) -> tuple[float, float]:
        """Returns lat/lon coordinates of the satellite at the end of the overpass."""
        return self.end_lat_deg_north, self.end_lon_deg_east

    @property
    def closest_coords(self) -> tuple[float, float]:
        """Returns lat/lon coordinates where the satellite is geographically closest to the site."""
        return self.closest_lat_deg_north, self.closest_lon_deg_east

    @property
    def duration(self) -> pd.Timedelta:
        """Returns the duration of the overpass."""
        return self.end_time - self.start_time

    def to_dict(self) -> dict:
        """Returns overpass info as a Python `dict`."""
        d = dict(
            site_name=self.site_name,
            site_lat_deg_north=self.site_lat_deg_north,
            site_lon_deg_east=self.site_lon_deg_east,
            site_radius_km=self.site_radius_km,
            start_index=self.start_index,
            end_index=self.end_index,
            start_time=self.start_time,
            end_time=self.end_time,
            start_lat_deg_north=self.start_lat_deg_north,
            start_lon_deg_east=self.start_lon_deg_east,
            end_lat_deg_north=self.end_lat_deg_north,
            end_lon_deg_east=self.end_lon_deg_east,
            closest_index=self.closest_index,
            closest_lat_deg_north=self.closest_lat_deg_north,
            closest_lon_deg_east=self.closest_lon_deg_east,
            closest_time=self.closest_time,
            closest_distance_km=self.closest_distance_km,
            along_track_distance_km=self.along_track_distance_km,
            frame_crosses_pole=self.frame_crosses_pole,
            samples=self.samples,
        )
        return d

    def to_dataframe(self) -> pd.DataFrame:
        """Returns overpass info as a `pandas.Dataframe`."""
        df = pd.DataFrame([self.to_dict()])
        df = df.astype(
            dict(
                site_name=str,
                site_lat_deg_north=float,
                site_lon_deg_east=float,
                site_radius_km=float,
                start_index=int,
                end_index=int,
                start_time=pd.Timestamp,
                end_time=pd.Timestamp,
                start_lat_deg_north=float,
                start_lon_deg_east=float,
                end_lat_deg_north=float,
                end_lon_deg_east=float,
                closest_index=int,
                closest_lat_deg_north=float,
                closest_lon_deg_east=float,
                closest_time=pd.Timestamp,
                closest_distance_km=float,
                along_track_distance_km=float,
                frame_crosses_pole=bool,
                samples=int,
            )
        )
        return df

closest_coords property 

closest_coords: tuple[float, float]

Returns lat/lon coordinates where the satellite is geographically closest to the site.

duration property 

duration: Timedelta

Returns the duration of the overpass.

end_coords property 

end_coords: tuple[float, float]

Returns lat/lon coordinates of the satellite at the end of the overpass.

index_range property 

index_range: tuple[int, int]

Returns start and end indecies of the overpass.

site_coords property 

site_coords: tuple[float, float]

Returns lat/lon coordinates of the overpassed site or center.

start_coords property 

start_coords: tuple[float, float]

Returns lat/lon coordinates of the satellite at the start of the overpass.

time_range property 

time_range: tuple[Timestamp, Timestamp]

Returns start and end times of the overpass.

to_dataframe 

to_dataframe() -> DataFrame

Returns overpass info as a pandas.Dataframe.

Source code in earthcarekit/overpass/_overpass_info.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def to_dataframe(self) -> pd.DataFrame:
    """Returns overpass info as a `pandas.Dataframe`."""
    df = pd.DataFrame([self.to_dict()])
    df = df.astype(
        dict(
            site_name=str,
            site_lat_deg_north=float,
            site_lon_deg_east=float,
            site_radius_km=float,
            start_index=int,
            end_index=int,
            start_time=pd.Timestamp,
            end_time=pd.Timestamp,
            start_lat_deg_north=float,
            start_lon_deg_east=float,
            end_lat_deg_north=float,
            end_lon_deg_east=float,
            closest_index=int,
            closest_lat_deg_north=float,
            closest_lon_deg_east=float,
            closest_time=pd.Timestamp,
            closest_distance_km=float,
            along_track_distance_km=float,
            frame_crosses_pole=bool,
            samples=int,
        )
    )
    return df

to_dict 

to_dict() -> dict

Returns overpass info as a Python dict.

Source code in earthcarekit/overpass/_overpass_info.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def to_dict(self) -> dict:
    """Returns overpass info as a Python `dict`."""
    d = dict(
        site_name=self.site_name,
        site_lat_deg_north=self.site_lat_deg_north,
        site_lon_deg_east=self.site_lon_deg_east,
        site_radius_km=self.site_radius_km,
        start_index=self.start_index,
        end_index=self.end_index,
        start_time=self.start_time,
        end_time=self.end_time,
        start_lat_deg_north=self.start_lat_deg_north,
        start_lon_deg_east=self.start_lon_deg_east,
        end_lat_deg_north=self.end_lat_deg_north,
        end_lon_deg_east=self.end_lon_deg_east,
        closest_index=self.closest_index,
        closest_lat_deg_north=self.closest_lat_deg_north,
        closest_lon_deg_east=self.closest_lon_deg_east,
        closest_time=self.closest_time,
        closest_distance_km=self.closest_distance_km,
        along_track_distance_km=self.along_track_distance_km,
        frame_crosses_pole=self.frame_crosses_pole,
        samples=self.samples,
    )
    return d

get_overpass_info 

get_overpass_info(
    ds: str | Dataset,
    site: SiteLike,
    radius_km: float | int = 100.0,
    *,
    time_var: str = TIME_VAR,
    lat_var: str = TRACK_LAT_VAR,
    lon_var: str = TRACK_LON_VAR,
    along_track_dim: str = ALONG_TRACK_DIM
) -> OverpassInfo

Extract details about an overpass, including duration, distance, time, closest index, etc.

Parameters:

Name Type Description Default
ds str | Dataset

Path to or instance of a dataset containing along-track satellite data.

 required
site SiteLike

Site name or object over which the satellite is passing.

 required
radius_km float | int

Radius to look for an overpass in kilometers. Defaults to 100.

 100.0
time_var str

Name of the dataset variable containing time data. Defaults to "time".

 TIME_VAR
lat_var str

Name of the dataset variable containing latitude data. Defaults to "latitude".

 TRACK_LAT_VAR
lon_var str

Name of the dataset variable containing longitude data. Defaults to "longitude".

 TRACK_LON_VAR
along_track_dim str

Name of the along-track or temporal dataset dimension. Defaults to "along_track".

 ALONG_TRACK_DIM

Raises:

Type Description
TypeError

If ds is not of type str (i.e., filepath) or xr.Dataset.

Returns:

Name Type Description
OverpassInfo OverpassInfo

description
Source code in earthcarekit/overpass/_overpass_info.py 
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
def get_overpass_info(
    ds: str | xr.Dataset,
    site: SiteLike,
    radius_km: float | int = 100.0,
    *,
    time_var: str = TIME_VAR,
    lat_var: str = TRACK_LAT_VAR,
    lon_var: str = TRACK_LON_VAR,
    along_track_dim: str = ALONG_TRACK_DIM,
) -> OverpassInfo:
    """
    Extract details about an overpass, including duration, distance, time, closest index, etc.

    Args:
        ds (str | xr.Dataset): Path to or instance of a dataset containing along-track satellite data.
        site (SiteLike): Site name or object over which the satellite is passing.
        radius_km (float | int, optional): Radius to look for an overpass in kilometers. Defaults to 100.
        time_var (str, optional): Name of the dataset variable containing time data. Defaults to "time".
        lat_var (str, optional): Name of the dataset variable containing latitude data. Defaults to "latitude".
        lon_var (str, optional): Name of the dataset variable containing longitude data. Defaults to "longitude".
        along_track_dim (str, optional): Name of the along-track or temporal dataset dimension. Defaults to "along_track".

    Raises:
        TypeError: If `ds` is not of type `str` (i.e., filepath) or `xr.Dataset`.

    Returns:
        OverpassInfo: _description_
    """
    if isinstance(ds, str):
        with read_product(ds) as _ds:
            result = _get_overpass_info(
                _ds,
                radius_km=radius_km,
                site=site,
                time_var=time_var,
                lat_var=lat_var,
                lon_var=lon_var,
                along_track_dim=along_track_dim,
            )
    elif isinstance(ds, xr.Dataset):
        result = _get_overpass_info(
            ds,
            radius_km=radius_km,
            site=site,
            time_var=time_var,
            lat_var=lat_var,
            lon_var=lon_var,
            along_track_dim=along_track_dim,
        )
    else:
        raise TypeError(
            f"`ds` has invalid type '{type(ds).__name__}', expected 'str' (i.e. filepath) or 'xr.Dataset'"
        )

    return result