skyweaver.tracks

Satellite track calculations for ground and observatory sky coordinates.

GroundTrack dataclass

GroundTrack(orbit, timegrid, latitude_deg, longitude_deg)

Sub-satellite ground track sampled on a time grid.

n_times property

n_times

Return the number of sampled time points.

summary

summary()

Return a compact human-readable summary.

Source code in src/skyweaver/tracks.py

def summary(self) -> str:
    """Return a compact human-readable summary."""
    return f"GroundTrack(orbit={self.orbit.name!r}, n_times={self.n_times})"

PassInterval dataclass

PassInterval(start_utc, stop_utc)

UTC bounds for a single above-horizon pass.

duration_s property

duration_s

Return the interval duration in seconds.

datetimes

datetimes(cadence_s)

Return sampled UTC datetimes over the interval.

Source code in src/skyweaver/tracks.py

def datetimes(self, cadence_s: float) -> list[datetime]:
    """Return sampled UTC datetimes over the interval."""
    return _sample_interval_datetimes(
        self.start_utc,
        self.stop_utc,
        cadence_s,
    )

SkyPass dataclass

SkyPass(orbit, observatory, interval, cadence_s, start_index, stop_index, altitude_deg, azimuth_deg, range_km)

Single contiguous above-horizon satellite pass.

max_altitude_deg property

max_altitude_deg

Return the maximum altitude during the pass.

n_times property

n_times

Return the number of samples in the pass.

start_utc property

start_utc

Return the UTC start time of the pass.

stop_utc property

stop_utc

Return the UTC stop time of the pass.

datetimes

datetimes()

Return UTC datetimes for samples in this pass.

Source code in src/skyweaver/tracks.py

def datetimes(self) -> list[datetime]:
    """Return UTC datetimes for samples in this pass."""
    if self.cadence_s is None:
        raise ValueError("This pass does not have a regular stored cadence")
    return self.interval.datetimes(self.cadence_s)

SkyTrack dataclass

SkyTrack(orbit, observatory, altitude_deg, azimuth_deg, range_km, cadence_s=None, timegrid=None, pass_intervals=(), pass_sample_counts=None)

Satellite sky track sampled at an observatory.

n_times property

n_times

Return the number of sampled time points.

visible property

visible

Return boolean mask where satellite is above the horizon.

datetimes

datetimes()

Return UTC datetimes for the stored samples.

Source code in src/skyweaver/tracks.py

def datetimes(self) -> list[datetime]:
    """Return UTC datetimes for the stored samples."""
    if self.timegrid is not None:
        return self.timegrid.datetimes()

    if self.cadence_s is None:
        raise ValueError("This SkyTrack does not have a regular stored cadence")

    datetimes: list[datetime] = []
    for interval in self.pass_intervals:
        datetimes.extend(interval.datetimes(self.cadence_s))
    return datetimes

passes

passes()

Return contiguous above-horizon passes.

Source code in src/skyweaver/tracks.py

def passes(self) -> list["SkyPass"]:
    """Return contiguous above-horizon passes."""
    if self.pass_sample_counts is not None and len(self.pass_intervals) > 0:
        edges = np.r_[0, np.cumsum(self.pass_sample_counts)]
        passes: list[SkyPass] = []

        for i, interval in enumerate(self.pass_intervals):
            start = int(edges[i])
            stop = int(edges[i + 1])

            passes.append(
                SkyPass(
                    orbit=self.orbit,
                    observatory=self.observatory,
                    interval=interval,
                    cadence_s=self.cadence_s,
                    start_index=start,
                    stop_index=stop,
                    altitude_deg=self.altitude_deg[start:stop],
                    azimuth_deg=self.azimuth_deg[start:stop],
                    range_km=self.range_km[start:stop],
                )
            )

        return passes

    visible = self.visible

    if not np.any(visible):
        return []

    visible_i = visible.astype(int)
    changes = np.diff(visible_i)

    starts = np.where(changes == 1)[0] + 1
    stops = np.where(changes == -1)[0] + 1

    if visible[0]:
        starts = np.r_[0, starts]

    if visible[-1]:
        stops = np.r_[stops, len(visible)]

    if self.timegrid is None:
        raise RuntimeError("Cannot derive coarse pass metadata without a TimeGrid")

    coarse_times = self.timegrid.datetimes()
    passes: list[SkyPass] = []

    for start, stop in zip(starts, stops, strict=True):
        interval = PassInterval(
            start_utc=coarse_times[int(start)],
            stop_utc=coarse_times[int(stop) - 1],
        )

        passes.append(
            SkyPass(
                orbit=self.orbit,
                observatory=self.observatory,
                interval=interval,
                cadence_s=self.cadence_s,
                start_index=int(start),
                stop_index=int(stop),
                altitude_deg=self.altitude_deg[start:stop],
                azimuth_deg=self.azimuth_deg[start:stop],
                range_km=self.range_km[start:stop],
            )
        )

    return passes

summary

summary()

Return a compact human-readable summary.

Source code in src/skyweaver/tracks.py

def summary(self) -> str:
    """Return a compact human-readable summary."""
    return f"SkyTrack(orbit={self.orbit.name!r}, observatory={self.observatory.name!r}, n_times={self.n_times})"

to_healpix

to_healpix(nside, *, unique_per_pass=True)

Convert the sky track to a HEALPix map in local alt-az coordinates.

Parameters:

Name	Type	Description	Default
nside	int	HEALPix nside parameter.	required
unique_per_pass	bool	If True, each pixel is counted at most once per pass. If False, every visible sample contributes to the map.	True

Returns:

Type	Description
ndarray	HEALPix map of pass/sample counts.

Source code in src/skyweaver/tracks.py

def to_healpix(
    self,
    nside: int,
    *,
    unique_per_pass: bool = True,
) -> np.ndarray:
    """Convert the sky track to a HEALPix map in local alt-az coordinates.

    Parameters
    ----------
    nside
        HEALPix nside parameter.
    unique_per_pass
        If True, each pixel is counted at most once per pass. If False,
        every visible sample contributes to the map.

    Returns
    -------
    np.ndarray
        HEALPix map of pass/sample counts.
    """
    npix = hp.nside2npix(nside)
    healpix_map = np.zeros(npix, dtype=float)

    for sat_pass in self.passes():
        if sat_pass.n_times == 0:
            continue

        theta = np.deg2rad(90.0 - sat_pass.altitude_deg)
        phi = np.deg2rad(sat_pass.azimuth_deg)

        pixels = hp.ang2pix(nside, theta, phi)

        if unique_per_pass:
            pixels = np.unique(pixels)

        np.add.at(healpix_map, pixels, 1.0)

    return healpix_map

ground_track

ground_track(orbit, timegrid)

Compute the sub-satellite ground track for an orbit.

Parameters:

Name	Type	Description	Default
orbit	OrbitSpec	Orbit specification to propagate.	required
timegrid	TimeGrid	Time grid on which to evaluate the orbit.	required

Returns:

Type	Description
GroundTrack	Sub-satellite latitude and longitude as a function of time.

Source code in src/skyweaver/tracks.py

def ground_track(orbit: OrbitSpec, timegrid: TimeGrid) -> GroundTrack:
    """Compute the sub-satellite ground track for an orbit.

    Parameters
    ----------
    orbit
        Orbit specification to propagate.
    timegrid
        Time grid on which to evaluate the orbit.

    Returns
    -------
    GroundTrack
        Sub-satellite latitude and longitude as a function of time.
    """
    satellite = orbit.to_earth_satellite()
    times = timegrid.skyfield()

    geocentric = satellite.at(times)
    subpoint = wgs84.subpoint_of(geocentric)

    latitude_deg = np.asarray(subpoint.latitude.degrees, dtype=float)
    longitude_deg = np.asarray(subpoint.longitude.degrees, dtype=float)

    return GroundTrack(
        orbit=orbit,
        timegrid=timegrid,
        latitude_deg=latitude_deg,
        longitude_deg=longitude_deg,
    )

sky_track

sky_track(orbit, observatory, timegrid, *, pass_cadence_s=None)

Compute the satellite sky track as seen from an observatory.

Parameters:

Name	Type	Description	Default
orbit	OrbitSpec	Orbit specification to propagate.	required
observatory	Observatory	Observatory from which to view the satellite.	required
timegrid	TimeGrid	Time interval over which to search/evaluate the satellite.	required
pass_cadence_s	float | None	Optional finer cadence, in seconds, used to evaluate only the above-horizon pass windows identified by Skyfield event finding.	None

Returns:

Type	Description
SkyTrack	Altitude, azimuth, and range as a function of time.

Source code in src/skyweaver/tracks.py

def sky_track(
    orbit: OrbitSpec,
    observatory: Observatory,
    timegrid: TimeGrid,
    *,
    pass_cadence_s: float | None = None,
) -> SkyTrack:
    """Compute the satellite sky track as seen from an observatory.

    Parameters
    ----------
    orbit
        Orbit specification to propagate.
    observatory
        Observatory from which to view the satellite.
    timegrid
        Time interval over which to search/evaluate the satellite.
    pass_cadence_s
        Optional finer cadence, in seconds, used to evaluate only the
        above-horizon pass windows identified by Skyfield event finding.

    Returns
    -------
    SkyTrack
        Altitude, azimuth, and range as a function of time.
    """
    satellite = orbit.to_earth_satellite()
    difference = satellite - observatory.skyfield_topos

    if pass_cadence_s is None:
        times = timegrid.skyfield()
        topocentric = difference.at(times)

        altitude, azimuth, distance = topocentric.altaz()

        return SkyTrack(
            orbit=orbit,
            observatory=observatory,
            altitude_deg=np.asarray(altitude.degrees, dtype=float),
            azimuth_deg=np.asarray(azimuth.degrees, dtype=float),
            range_km=np.asarray(distance.km, dtype=float),
            cadence_s=timegrid.cadence_s,
            timegrid=timegrid,
        )

    if pass_cadence_s <= 0.0:
        raise ValueError("pass_cadence_s must be positive")

    ts = load.timescale()
    t0 = ts.from_datetime(timegrid.start)
    t1 = ts.from_datetime(timegrid.stop)

    event_times, event_codes = satellite.find_events(
        observatory.skyfield_topos,
        t0,
        t1,
        altitude_degrees=0.0,
    )

    event_times_utc = list(event_times.utc_datetime())
    intervals = _pair_visibility_events(
        event_times_utc,
        event_codes,
        timegrid.start,
        timegrid.stop,
    )

    if len(intervals) == 0:
        return SkyTrack(
            orbit=orbit,
            observatory=observatory,
            altitude_deg=np.asarray([], dtype=float),
            azimuth_deg=np.asarray([], dtype=float),
            range_km=np.asarray([], dtype=float),
            cadence_s=pass_cadence_s,
            pass_intervals=(),
            pass_sample_counts=np.asarray([], dtype=int),
        )

    altitude_all: list[np.ndarray] = []
    azimuth_all: list[np.ndarray] = []
    range_all: list[np.ndarray] = []
    pass_sample_counts: list[int] = []

    for interval in intervals:
        pass_datetimes = interval.datetimes(pass_cadence_s)
        pass_times = ts.from_datetimes(pass_datetimes)

        topocentric = difference.at(pass_times)
        altitude, azimuth, distance = topocentric.altaz()

        altitude_deg = np.asarray(altitude.degrees, dtype=float)
        azimuth_deg = np.asarray(azimuth.degrees, dtype=float)
        range_km = np.asarray(distance.km, dtype=float)

        altitude_all.append(altitude_deg)
        azimuth_all.append(azimuth_deg)
        range_all.append(range_km)
        pass_sample_counts.append(len(pass_datetimes))

    return SkyTrack(
        orbit=orbit,
        observatory=observatory,
        altitude_deg=np.concatenate(altitude_all),
        azimuth_deg=np.concatenate(azimuth_all),
        range_km=np.concatenate(range_all),
        cadence_s=pass_cadence_s,
        pass_intervals=intervals,
        pass_sample_counts=np.asarray(pass_sample_counts, dtype=int),
    )