Skip to content

API reference#

earthcarekit.overpass

Utilities for processing satellite overpasses relative to ground stations.

Notes#

This module depends on other internal modules:

OverpassInfo dataclass #

Stores details about an EarthCARE satellite overpass.

Attributes:

Name Type Description
site_name str

Name of the site flown over.
site_lat_deg_north float

Site latitude in degrees north.
site_lon_deg_east float

Site longitude in degrees east.
site_radius_km float

Search radius around the site in kilometers.
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

Longitude at the start of the overpass.
end_lat_deg_north float

Latitude at the end of the overpass.
end_lon_deg_east float

Longitude at the end of the overpass.
closest_index int

Index of the sample geographically closest to the site.
closest_lat_deg_north float

Latitude of the closest sample.
closest_lon_deg_east float

Longitude of the closest sample.
closest_time Timestamp

Time of the closest sample.
closest_distance_km float

Distance to the closest sample in kilometers.
along_track_distance_km float

Distance along the overpass track within the radius.
frame_crosses_pole bool

Whether the track crosses a pole (any point, not just within radius).
samples int

Number of samples within the radius.
site Site

Site object.
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
@dataclass
class OverpassInfo:
    """Stores details about an EarthCARE satellite overpass.

    Attributes:
        site_name: Name of the site flown over.
        site_lat_deg_north: Site latitude in degrees north.
        site_lon_deg_east: Site longitude in degrees east.
        site_radius_km: Search radius around the site in kilometers.
        start_index: Index at the start of the overpass.
        end_index: Index at the end of the overpass.
        start_time: Time at the start of the overpass.
        end_time: Time at the end of the overpass.
        start_lat_deg_north: Latitude at the start of the overpass.
        start_lon_deg_east: Longitude at the start of the overpass.
        end_lat_deg_north: Latitude at the end of the overpass.
        end_lon_deg_east: Longitude at the end of the overpass.
        closest_index: Index of the sample geographically closest to the site.
        closest_lat_deg_north: Latitude of the closest sample.
        closest_lon_deg_east: Longitude of the closest sample.
        closest_time: Time of the closest sample.
        closest_distance_km: Distance to the closest sample in kilometers.
        along_track_distance_km: Distance along the overpass track within the radius.
        frame_crosses_pole: Whether the track crosses a pole (any point, not just within radius).
        samples: Number of samples within the radius.
        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 
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
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 
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
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

Extracts overpass details including duration, distance, time, and closest index.

Parameters:

Name Type Description Default
ds str | Dataset

Dataset or file path with along-track satellite data.

 required
site SiteLike

Site name or object over which the satellite passes.

 required
radius_km float | int

Search radius in kilometers; defaults to 100.

 100.0
time_var str

Time variable name.

 TIME_VAR
lat_var str

Latitude variable name.

 TRACK_LAT_VAR
lon_var str

Longitude variable name.

 TRACK_LON_VAR
along_track_dim str

Along-track dimension name.

 ALONG_TRACK_DIM

Returns:

Type Description
OverpassInfo

An OverpassInfo object with overpass metadata.
Source code in earthcarekit/overpass/_overpass_info.py 
329
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
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:
    """Extracts overpass details including duration, distance, time, and closest index.

    Args:
        ds: Dataset or file path with along-track satellite data.
        site: Site name or object over which the satellite passes.
        radius_km: Search radius in kilometers; defaults to 100.
        time_var: Time variable name.
        lat_var: Latitude variable name.
        lon_var: Longitude variable name.
        along_track_dim: Along-track dimension name.

    Returns:
        An `OverpassInfo` object with overpass metadata.
    """
    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