Utility Functions

tatc.utils.mean_anomaly_to_true_anomaly(mean_anomaly: float, eccentricity: float = 0) → float[source]

Approximates orbit true anomaly using a third-order series expansion.

Parameters:
  • mean_anomaly (float) – Orbit mean anomaly (degrees).

  • eccentricity (float) – Orbit eccentricity.

Returns:

Orbit true anomaly (degrees).

Return type:

float

tatc.utils.true_anomaly_to_mean_anomaly(true_anomaly: float, eccentricity: float = 0) → float[source]

Approximates orbit mean anomaly using a third-order series expansion.

Parameters:
  • true_anomaly (float) – Orbit true anomaly (degrees).

  • eccentricity (float) – Orbit eccentricity.

Returns:

Orbit mean anomaly (degrees).

Return type:

float

tatc.utils.compute_number_samples(distance: float) → int[source]

Compute the number of global samples required to achieve a typical sample distance (meters) assuming equal spacing, by dividing the Earth’s surface area (assuming a mean sphere) by the area of a spherical cap whose angular radius corresponds to half the sample distance. The result is truncated (not rounded), so the achieved average sample spacing is always at least the requested distance, never less. Requires distance > 0.

Parameters:

distance (float) – The typical distance between samples (meters).

Returns:

The number of global samples.

Return type:

int

tatc.utils.swath_width_to_field_of_regard(altitude: float, swath_width: float, elevation: float = 0) → float[source]

Fast computation of the field of regard (the total angular width an instrument must be able to point or scan across) required to observe a specified ground swath width, assuming a spherical Earth (using the mean Earth radius) and a circular orbit at constant altitude.

Parameters:
  • altitude (float) – Altitude (meters) above the mean Earth radius for the observing instrument.

  • swath_width (float) – Ground swath width (meters): the cross-track distance, measured along the Earth’s surface, at the specified elevation.

  • elevation (float) – Elevation (meters) above the mean Earth radius of the observed swath.

Returns:

The field of regard (degrees): the full angular width, centered on nadir, that the instrument must be able to point across to observe the swath.

Return type:

float

tatc.utils.swath_width_to_field_of_view(altitude: float, swath_width: float, look_angle: float = 0, elevation: float = 0) → float[source]

Fast computation of the field of view (the angular extent, as seen from the satellite, spanning the near to far edge of a swath) required to observe a specified ground swath width centered on a given off-nadir look angle, assuming a spherical Earth (using the mean Earth radius) and a circular orbit at constant altitude. Unlike swath_width_to_field_of_regard, the swath is not centered on nadir, so the field of view spans asymmetrically between the near and far edges of the swath.

Parameters:
  • altitude (float) – Altitude (meters) above the mean Earth radius for the observing instrument.

  • swath_width (float) – Ground swath width (meters): the cross-track distance, measured along the Earth’s surface, centered on the look angle direction.

  • look_angle (float) – Off-nadir look angle (degrees), measured at the satellite, to the center of the swath. Saturates at the horizon-limited maximum.

  • elevation (float) – Elevation (meters) above the mean Earth radius of the observed swath.

Returns:

The field of view (degrees): the angular extent, as seen from the satellite, spanning the near to far edge of the swath.

Return type:

float

tatc.utils.field_of_regard_to_swath_width(altitude: float, field_of_regard: float, elevation: float = 0) → float[source]

Fast computation of the ground swath width observable for a specified field of regard, assuming a spherical Earth (using the mean Earth radius) and a circular orbit at constant altitude. This is the inverse of swath_width_to_field_of_regard. A field_of_regard at or beyond the horizon-limited maximum (i.e. pointing to the horizon) saturates to the maximum observable swath width rather than growing without bound.

Parameters:
  • altitude (float) – Altitude (meters) above the mean Earth radius for the observing instrument.

  • field_of_regard (float) – The full angular width (degrees), centered on nadir, that the instrument points or scans across.

  • elevation (float) – Elevation (meters) above the mean Earth radius of the observed swath.

Returns:

The ground swath width (meters): the cross-track distance, measured along the Earth’s surface, at the specified elevation.

Return type:

float

tatc.utils.buffer_footprint(geometry: Geometry, to_crs: Transformer, from_crs: Transformer, swath_width: float, elevation: float) → Polygon | MultiPolygon[source]

Buffers a ground track point (in EPSG:4326 coordinates) to create a footprint, by reprojecting to a distance-preserving CRS, buffering by half the swath width, and reprojecting back.

Parameters:
  • geometry (shapely.Geometry) – The geometry (with EPSG:4326 coordinates) to buffer.

  • to_crs (pyproj.Transformer) – Transformer from EPSG:4326 to the CRS in which to perform the buffer (must use meters).

  • from_crs (pyproj.Transformer) – Transformer back from the buffering CRS to EPSG:4326.

  • swath_width (float) – The swath width (meters) to buffer.

  • elevation (float) – The elevation (meters) at which project the buffered polygon.

Returns:

The buffered footprint.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

tatc.utils.buffer_target(geometry: Geometry, altitude: float, inclination: float, field_of_regard: float, time_step: float, distance_crs: str | None = None, distance_scaling: float = 1.0) → Polygon | MultiPolygon[source]

Buffers a target geometry to support culling operations. Selects a buffer distance equal to the distance traveled in one time step plus half of the field of regard swath width, so that no point still reachable within the time step is incorrectly excluded. The ground distance traveled uses the ground velocity at the equator, which is the fastest (most conservative, largest-distance) point for any given inclination.

Deprecated: buffering in a planar (equidistant cylindrical) projection does not conservatively bound observations near the poles or across the anti-meridian. The analysis functions instead cull to the periods when an instrument’s field of regard may observe a region (see tatc.analysis.region_sampling.compute_region_access_periods). This function will be removed in a future release.

Parameters:
  • geometry (shapely.Geometry) – The target geometry (with EPSG:4326 coordinates) to buffer.

  • altitude (float) – The spacecraft orbit altitude (meters).

  • inclination (float) – The spacecraft orbit inclination (degrees).

  • field_of_regard (float) – The spacecraft instrument field of regard (degrees).

  • time_step (float) – The simulation time step (seconds).

  • distance_crs (str | None) – The coordinate reference system in which to perform distance calculations. Defaults to None, which builds an equidistant cylindrical projection whose true-scale parallel (lat_ts) is set to geometry’s own most poleward latitude. This keeps the buffer conservative (true ground distance >= the requested distance) at every latitude within geometry.

  • distance_scaling (float) – A multiplicative scaling factor to adjust the buffer distance (default: 1.0).

Returns:

The buffered geometry.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

tatc.utils.compute_footprint(orbit_track: Geocentric, cross_track_field_of_view: float, along_track_field_of_view: float, roll_angle: float = 0, pitch_angle: float = 0, is_rectangular: bool = False, number_points: int | None = None, elevation: float = 0, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, nadir_reference: NadirReference = NadirReference.GEODETIC, view_geometry: ViewGeometry = ViewGeometry.FRAME, ground_elevation: float = 0, attitude: Any | None = None, yaw_angle: float = 0) → list[Polygon | MultiPolygon][source]

Compute the instantaneous instrument footprint. Supports both a scalar (single-time) and vectorized (multi-time) orbit_track; the result is always a list, with one footprint per time (length 1 for a scalar orbit_track). Toward an elevation above the instrument (for example, from a surface platform), the footprint is the part of the view above the horizon, clipped to the lines of sight tangent to the ground: empty for a view entirely below the horizon, or an annulus for a view about nadir that reaches above it.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – The satellite position/velocity.

  • cross_track_field_of_view (float) – The angular (degrees) view orthogonal to velocity.

  • along_track_field_of_view (float) – The angular (degrees) view in direction of velocity.

  • roll_angle (float) – The left/right look angle (degrees), a rotation about the along-track axis, positive to the left of the direction of motion.

  • pitch_angle (float) – The fore/aft look angle (degrees), a rotation about the rolled cross-track axis, positive forward (in ViewGeometry.SCAN, the tilt of the scan plane: a rotation about the cross-track axis applied before the roll angle).

  • is_rectangular (bool) – True, if this is a rectangular sensor.

  • number_points (int | None) – The required number of polygon points to generate: per side for a rectangular sensor, or total for an elliptical sensor. Defaults to the runtime configuration.

  • elevation (float) – The elevation (meters) at which project the footprint.

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • nadir_reference (NadirReference) – The definition of the nadir direction from which the view is rotated.

  • view_geometry (ViewGeometry) – The geometry in which the fields of view are defined.

  • ground_elevation (float) – The elevation (meters) of the ground, which blocks rays toward an elevation above the instrument.

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

  • yaw_angle (float) – The instrument yaw angle (degrees), a rotation about the nadir axis applied before the roll and pitch angles, positive turning the along-track axis to the left.

Returns:

The instrument footprint(s).

Return type:

list[shapely.geometry.Polygon | shapely.geometry.MultiPolygon]

tatc.utils.compute_limb(orbit_track: Geocentric, number_points: int = 16, elevation: float = 0) → list[Polygon | MultiPolygon][source]

Compute the instantaneous limb (the outline of the visible Earth disk). Supports both a scalar (single-time) and vectorized (multi-time) orbit_track; the result is always a list, with one limb per time (length 1 for a scalar orbit_track).

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – The satellite position/velocity.

  • number_points (int) – The required number of polygon points to generate.

  • elevation (float) – The elevation (meters) at which project the limb.

Returns:

The limb(s).

Return type:

list[shapely.geometry.Polygon | shapely.geometry.MultiPolygon]

tatc.utils.compute_projected_ray_position(orbit_track: Geocentric, cross_track_field_of_view: float, along_track_field_of_view: float, roll_angle: float = 0, pitch_angle: float = 0, is_rectangular: bool = False, angle: float = 0, elevation: float = 0, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, nadir_reference: NadirReference = NadirReference.GEODETIC, tilt_angle: float = 0, ground_elevation: float = 0, attitude: Any | None = None, yaw_angle: float = 0) → GeographicPosition[source]

Get the location of a projected ray from an instrument. The ray is cast from the satellite position toward the WGS 84 geoid at the specified elevation; if it misses the geoid entirely (e.g. an off-nadir angle pointing past the horizon), the projected position instead falls back to the nearest point on the visible Earth limb. Toward an elevation above the instrument (for example, from a surface platform), a ray blocked by the ground below the horizon instead falls back to the line of sight tangent to the ground in the same azimuth. Zero roll, pitch, and field of view center on nadir: by default, the geodetic nadir (the WGS 84 ellipsoid surface normal through the satellite), matching Skyfield’s wgs84.subpoint_of/wgs84.geographic_position_of.

The view is rotated rigidly from nadir (the body’s axes, with an attitude), first by the yaw angle about the nadir axis (and the tilt angle about the cross-track axis), then by the roll angle about the along-track axis, then by the pitch angle about the rolled cross-track axis. Its shape is defined in the plane perpendicular to the boresight at unit distance (as for the focal plane of a camera): a rectangle with half widths tan(field_of_view / 2), or an ellipse inscribed in it.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • cross_track_field_of_view (float) – the instrument cross-track (orthogonal to velocity vector) field of view (degrees).

  • along_track_field_of_view (float) – the instrument along-track (parallel to velocity vector) field of view (degrees).

  • roll_angle (float) – the instrument roll angle (degrees), a rotation about the along-track axis, positive to the left of the direction of motion (right-hand about the velocity vector).

  • pitch_angle (float) – the instrument pitch angle (degrees), a rotation about the rolled cross-track axis, positive forward (in the direction of motion).

  • is_rectangular (bool) – True if the instrument view has a rectangular shape (otherwise elliptical).

  • angle (float) – ray angle (degrees) about the view center, measured from the cross-track axis on the left of the direction of motion (0 degrees) toward the along-track axis forward (90 degrees).

  • elevation (float) – The elevation (meters) at which project the footprint.

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • nadir_reference (NadirReference) – The definition of the nadir direction from which the view is rotated.

  • tilt_angle (float) – a rotation (degrees) about the cross-track axis, positive forward, applied before the roll angle (tilting the plane in which the roll angle is measured, as for the scan plane of a ViewGeometry.SCAN view).

  • ground_elevation (float) – The elevation (meters) of the ground, which blocks rays toward an elevation above the instrument.

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

  • yaw_angle (float) – the instrument yaw angle (degrees), a rotation about the nadir axis applied first, positive turning the along-track axis to the left (as an attitude’s yaw angle).

Returns:

the geographic position of the projected ray

Return type:

(skyfield.toposlib.GeographicPosition)

tatc.utils.compute_static_track(longitude: float, latitude: float, elevation: float = 0, heading: float = 0, t: Time | None = None) → Geocentric[source]

Compute the track of an instrument fixed in the Earth-fixed (ITRS) frame, as for a tower or a tethered balloon: a position and velocity, in the form of a satellite’s orbit track, from which instruments project their views (see compute_footprint). Its Earth-fixed velocity is a unit vector (1 m/s) in the local horizontal plane toward the heading, which only orients the view: the along-track axis points toward the heading, so that a positive roll angle looks to its left and a positive pitch angle looks toward it. The track is static: its Earth-fixed position and view do not change with time, while its inertial (GCRS) position and velocity rotate with the Earth (for example, to evaluate sunlit conditions).

Parameters:
  • longitude (float) – The geodetic longitude (degrees).

  • latitude (float) – The geodetic latitude (degrees).

  • elevation (float) – The elevation (meters) above the WGS 84 ellipsoid.

  • heading (float) – The azimuth (degrees, clockwise from north) of the along-track (forward) direction.

  • t (skyfield.timelib.Time | None) – The time(s), a scalar or a vector. Defaults to 2020-01-01 00:00:00 UTC.

Returns:

The position/velocity (with shape

(3,) for a scalar time or (3, N) for N times).

Return type:

skyfield.positionlib.Geocentric

tatc.utils.compute_view_tangents(orbit_track: Geocentric, target: GeographicPosition, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, roll_angle: float = 0, pitch_angle: float = 0, nadir_reference: NadirReference = NadirReference.GEODETIC, attitude: Any | None = None, yaw_angle: float = 0) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Compute the tangents of the along-track and cross-track view angles of a target relative to the center of an instrument’s view, using the same frame as compute_projected_ray_position: the line of sight to the target is parallel to boresight + along * along_axis + cross * cross_axis, where the boresight and axes are rotated from nadir by the yaw, roll, and pitch angles. With zero roll and pitch, a target with tangents (along, cross) lies at the center of a view with roll angle arctan(cross) and pitch angle arctan(along / sqrt(1 + cross**2)). Does not check whether the target is above the satellite’s horizon.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • roll_angle (float) – the instrument roll angle (degrees).

  • pitch_angle (float) – the instrument pitch angle (degrees).

  • nadir_reference (NadirReference) – The definition of the nadir direction from which the view is rotated.

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

  • yaw_angle (float) – the instrument yaw angle (degrees) about the nadir axis, applied before the roll angle.

Returns:

the along-track and

cross-track (positive left) view angle tangents (NaN if the target is not in front of the view).

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_view_angles(orbit_track: Geocentric, target: GeographicPosition, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, nadir_reference: NadirReference = NadirReference.GEODETIC, tilt_angle: float = 0, attitude: Any | None = None, yaw_angle: float = 0) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Compute the roll and pitch angles (degrees) that point a view’s center at a target, following the rigid rotation of compute_projected_ray_position (after the yaw angle about the nadir axis and the tilt angle about the cross-track axis, first by the roll angle about the along-track axis, then by the pitch angle about the rolled cross-track axis): the angles of the target in a ViewGeometry.SCAN view, whose scan plane is tilted by the tilt angle (the target’s scan angle and its along-track angle from the scan plane). Does not check whether the target is above the satellite’s horizon.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • nadir_reference (NadirReference) – The definition of the nadir direction from which the view is rotated.

  • tilt_angle (float) – the tilt angle (degrees) of the scan plane about the cross-track axis (positive forward).

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

  • yaw_angle (float) – the yaw angle (degrees) of the view about the nadir axis, applied before the tilt angle.

Returns:

the roll (positive

left) and pitch (positive forward) angles (degrees).

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_cone_and_azimuth(orbit_track: Geocentric, target: GeographicPosition, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, nadir_reference: NadirReference = NadirReference.GEODETIC, attitude: Any | None = None) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Compute the cone angle (from nadir) and the scan azimuth (about the nadir, from the along-track direction, positive to the left of the direction of motion) of the line of sight from a satellite to a target, as used to describe a conically scanning instrument. Does not check whether the target is above the satellite’s horizon.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • nadir_reference (NadirReference) – The definition of the nadir direction.

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

Returns:

the cone angle

(degrees, from 0 to 180) and scan azimuth (degrees, from -180 to 180).

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_ground_sample_size(orbit_track: Geocentric, target: GeographicPosition, along_track_angle: float, cross_track_angle: float, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, roll_angle: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 0, pitch_angle: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 0, nadir_reference: NadirReference = NadirReference.GEODETIC, tilt_angle: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 0, attitude: Any | None = None, yaw_angle: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 0) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Compute the size on the ground of an angular extent centered on the line of sight to a target, such as the instantaneous field of view of an instrument’s sample (or the angle between neighboring samples): the distances between the points where rays at half the extent on either side of the line of sight meet the WGS 84 ellipsoid (raised to the target’s elevation), along track and across track. The extents lie along the view’s along-track and cross-track axes (rotated from nadir by the yaw, tilt, roll, and pitch angles, see _compute_view_frame), each made perpendicular to the line of sight, so the sizes include the lengthening of a view off nadir and the curvature of the Earth. Rays that miss the Earth (beyond its limb) give NaN.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

  • along_track_angle (float) – the along-track angular extent (degrees).

  • cross_track_angle (float) – the cross-track angular extent (degrees).

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • roll_angle (numpy.typing.ArrayLike) – the view’s roll angle (degrees).

  • pitch_angle (numpy.typing.ArrayLike) – the view’s pitch angle (degrees).

  • nadir_reference (NadirReference) – The definition of the nadir direction from which the view is rotated.

  • tilt_angle (numpy.typing.ArrayLike) – the tilt angle (degrees) of a scan plane about the cross-track axis (positive forward).

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), from which the view is rotated, or None for a body aligned with the nadir frame (in velocity_frame).

  • yaw_angle (numpy.typing.ArrayLike) – the view’s yaw angle (degrees) about the nadir axis, applied before the tilt angle.

Returns:

the along-track

and cross-track sizes (meters).

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_ground_advance(orbit_track: Geocentric, target: GeographicPosition, seconds: float, velocity_frame: VelocityFrame = VelocityFrame.EARTH_FIXED, nadir_reference: NadirReference = NadirReference.GEODETIC, attitude: Any | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Compute the distance on the ground (meters) that a view fixed to the spacecraft advances at a target in a period of time: from the target to the point where the line of sight to it, held fixed relative to the view’s axes (the nadir frame, or the body’s axes with an attitude), meets the WGS 84 ellipsoid (raised to the target’s elevation) after the satellite moves along its Earth-fixed velocity for that period (a linear approximation over a short period, such as that of a scan). For a cross-track scanner, it is the spacing along track between the samples of consecutive scans, which is nearly constant across the scan. Rays that miss the Earth give NaN.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

  • seconds (float) – the period (seconds).

  • velocity_frame (VelocityFrame) – The reference frame of the velocity vector that defines the along-track direction.

  • nadir_reference (NadirReference) – The definition of the nadir direction.

  • attitude (Any) – The attitude of the spacecraft’s body (see tatc.schemas.Attitude and tatc.schemas.AttitudeSchedule), or None for a body aligned with the nadir frame (in velocity_frame).

Returns:

the distance (meters).

Return type:

numpy.typing.NDArray

tatc.utils.compute_specular_point(orbit_track: Geocentric, max_iterations: int = 30) → GeographicPosition[source]

Compute the specular point (the center of the sun glint) seen from a satellite: the point on the WGS 84 ellipsoid where the surface normal bisects the directions toward the satellite and toward the Sun, so that sunlight reflected by a level surface there (for example, calm water) reaches the satellite. At the specular point, the Sun and the satellite are at the same elevation angle, in opposite azimuths. The point is found by Newton’s method on the geodetic coordinates, from the point beneath the bisector of the directions toward the satellite and the Sun from the Earth’s center. It is undefined (NaN) where the Sun is below the horizon at the point, as when the satellite is over the night side of the Earth.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • max_iterations (int) – The maximum number of iterations.

Returns:

the specular point (one for each

time of the orbit track).

Return type:

skyfield.toposlib.GeographicPosition

tatc.utils.compute_glint_angle(orbit_track: Geocentric, target: GeographicPosition) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Compute the glint angle (degrees) at a target: the angle between the direction from the target toward the satellite and the direction of the Sun’s specular reflection at the target (the direction toward the Sun mirrored about the WGS 84 surface normal). It is zero at the specular point (see compute_specular_point), where a level surface reflects sunlight toward the satellite, and grows away from it. Sun glint contaminates observations of water (for example, of ocean color) at small glint angles, typically below about 20 to 30 degrees, whereas glint observations (for example, of greenhouse gases over the ocean) seek them.

Parameters:
  • orbit_track (skyfield.positionlib.Geocentric) – the satellite orbit track.

  • target (skyfield.toposlib.GeographicPosition) – the target position (a single target, or one target for each time of the orbit track).

Returns:

the glint angle (degrees).

Return type:

numpy.typing.NDArray

tatc.utils.compute_subsolar_latitude(at: datetime) → float[source]

Computes the subsolar latitude (degrees): the geocentric latitude of the Sun’s apparent direction, or its declination of date.

Parameters:

at (datetime.datetime) – The time (timezone-aware).

Returns:

The subsolar latitude (degrees).

Return type:

float

class tatc.utils.VelocityFrame(value)[source]

Enumeration of reference frames for the velocity vector that defines an instrument’s along-track direction (and hence its cross-track direction, orthogonal to velocity and nadir).

EARTH_FIXED = 'earth_fixed'

the field of view is aligned with the ground track, as for a yaw-steered spacecraft (for example, zero-Doppler steering for synthetic aperture radar).

Type:

Velocity relative to the rotating Earth

INERTIAL = 'inertial'

the field of view is aligned with the orbit plane, as for a spacecraft without yaw steering. Near the equator, the field of view is rotated by up to about 4 degrees (in low Earth orbit) relative to the ground track.

Type:

Inertial (orbital) velocity

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class tatc.utils.NadirReference(value)[source]

Enumeration of definitions of the nadir direction, from which an instrument’s view is rotated. The two coincide over the equator and the poles and otherwise differ by up to about 0.19 degrees (at middle latitudes), which shifts a projected view by up to about 2.7 km from 800 km altitude.

GEOCENTRIC = 'geocentric'

from the satellite toward the Earth’s center.

Type:

The geocentric direction

GEODETIC = 'geodetic'

the WGS 84 ellipsoid surface normal through the satellite, toward the Earth (matching Skyfield’s sub-satellite point).

Type:

The geodetic vertical

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class tatc.utils.ViewGeometry(value)[source]

Enumeration of the geometries in which a pointed instrument’s view (its fields of view and pixels) is defined.

FRAME = 'frame'

In a plane perpendicular to the boresight (as for the focal plane of a framing camera or a pushbroom array): a rectangle with half widths tan(field_of_view / 2), or an ellipse inscribed in it. The angular extent along track narrows away from the view center across track (in proportion to the cosine of the cross-track angle).

SCAN = 'scan'

the pitch angle tilts the scan plane (a rotation about the cross-track axis, as for a scanner that tilts fore or aft), and each direction is the tilted nadir rotated by a cross-track (scan) angle about the tilted along-track axis and then by an along-track angle about the rotated cross-track axis, with the fields of view as the ranges of these angles about the roll angle and the scan plane. The angular extent along track is constant across the scan, so the footprint widens along track away from nadir.

Type:

In angles (as for a cross-track scanner or a radar)

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

tatc.utils.compute_field_of_regard(altitude: float, min_elevation_angle: float, elevation: float = 0) → float[source]

Fast computation of field of regard for observation with a minimum altitude angle.

Parameters:
  • altitude (float) – Altitude (meters) above WGS 84 datum for the observing instrument.

  • min_elevation_angle (float) – The minimum elevation angle (degrees) for observation.

  • elevation (float) – Elevation (meters) above WGS 84 datum to observe.

Returns:

Angular width (degrees) of observation.

Return type:

float

tatc.utils.compute_min_elevation_angle(altitude: float, field_of_regard: float, elevation: float = 0) → float[source]

Fast computation of minimum elevation angle required to observe a point.

Parameters:
  • altitude (float) – Altitude (meters) above WGS 84 datum for the observing instrument.

  • field_of_regard (float) – Angular width (degrees) of observation.

  • elevation (float) – Elevation (meters) above WGS 84 datum to observe.

Returns:

The minimum elevation angle (degrees) for observation.

Return type:

float

tatc.utils.compute_local_incidence_angle(elevation_angle: float | ndarray, azimuth: float | ndarray, slope: float | ndarray = 0, aspect: float | ndarray = 0) → float | ndarray[source]

Compute the local incidence angle at a target on sloped terrain: the angle between the line of sight to the satellite and the normal to the terrain surface. On flat terrain (zero slope), it is the incidence angle on the WGS 84 ellipsoid, 90 degrees less the satellite’s elevation angle. Terrain facing the satellite (an aspect toward its azimuth) reduces the angle by up to the slope, as for the foreshortened slopes in a side-looking radar image, and terrain facing away increases it. An angle above 90 degrees means the satellite views the back of the slope, so the target is hidden (in a radar shadow, or out of an optical sensor’s view).

The satellite’s elevation angle and azimuth are measured from the target’s local (geodetic) horizon, as by the sat_alt and sat_az columns of observations and ground pixels with satellite angles (see tatc.analysis.collect_observations and tatc.analysis.collect_ground_pixels). See tatc.preprocess.compute_terrain_slope_aspect for the slope and aspect of a digital elevation model.

Parameters:
  • elevation_angle (float | numpy.ndarray) – The satellite’s elevation angle (degrees) above the target’s horizon.

  • azimuth (float | numpy.ndarray) – The satellite’s azimuth (degrees, clockwise from north) from the target.

  • slope (float | numpy.ndarray) – The terrain slope (degrees from horizontal).

  • aspect (float | numpy.ndarray) – The terrain aspect: the azimuth (degrees, clockwise from north) of the downslope direction, which the slope faces.

Returns:

The local incidence angle (degrees).

Return type:

float | numpy.ndarray

tatc.utils.semimajor_axis_to_orbit_period(semimajor_axis: float) → float[source]

Fast computation of orbital period from Kepler’s third law, assuming a circular orbit around a spherical Earth.

Parameters:

semimajor_axis (float) – Orbit semimajor axis (meters).

Returns:

Orbital period (seconds).

Return type:

float

tatc.utils.semimajor_axis_to_mean_motion(semimajor_axis: float) → float[source]

Fast computation of mean motion (average angular rate) from Kepler’s third law, assuming a circular orbit around a spherical Earth.

Parameters:

semimajor_axis (float) – Orbit semimajor axis (meters).

Returns:

Orbit mean motion (degrees/second).

Return type:

float

tatc.utils.mean_motion_to_orbit_period(mean_motion: float) → float[source]

Fast computation of orbital period: the time (360 degrees of mean motion) to complete one revolution. This function is its own inverse: calling it again on a period (seconds) recovers the mean motion (degrees/second), since both are 360 divided by the other.

Parameters:

mean_motion (float) – Orbit mean motion (degrees/second).

Returns:

Orbital period (seconds).

Return type:

float

tatc.utils.mean_motion_to_semimajor_axis(mean_motion: float) → float[source]

Fast computation of semimajor axis from Kepler’s third law, assuming a circular orbit around a spherical Earth. This is the inverse of semimajor_axis_to_mean_motion.

Parameters:

mean_motion (float) – Orbit mean motion (degrees/second).

Returns:

The semimajor axis (meters).

Return type:

float

tatc.utils.compute_apoapsis_radius(semimajor_axis: float, eccentricity: float) → float[source]

Fast computation of the apoapsis radius: the maximum orbit-to-Earth’s- center distance, at the far point of the ellipse from the focus.

Parameters:
  • semimajor_axis (float) – Orbit semimajor axis (meters).

  • eccentricity (float) – Orbit eccentricity.

Returns:

The apoapsis radius (meters).

Return type:

float

tatc.utils.compute_orbit_inertial_velocity(mean_altitude: float) → float[source]

Fast computation of orbit inertial velocity (the orbital speed relative to a non-rotating, Earth-centered frame) assuming a circular orbit around a spherical Earth (using the mean Earth radius).

Parameters:

mean_altitude (float) – Orbit mean altitude (meters) above the mean Earth radius.

Returns:

Inertial orbit velocity (meters/second).

Return type:

float

tatc.utils.compute_ground_inertial_velocity(mean_altitude: float, elevation: float = 0) → float[source]

Fast computation of the inertial velocity (relative to a non-rotating, Earth-centered frame) of the sub-satellite point projected onto a sphere at the specified elevation, assuming a circular orbit around a spherical Earth (using the mean Earth radius). Since the projected point shares the satellite’s angular velocity, its linear velocity scales with its (smaller, or larger if elevation exceeds mean_altitude) radius relative to the orbit’s radius.

Parameters:
  • mean_altitude (float) – Orbit mean altitude (meters) above the mean Earth radius.

  • elevation (float) – Surface elevation (meters) above the mean Earth radius at which to project the ground point.

Returns:

Ground point inertial velocity (meters/second).

Return type:

float

tatc.utils.compute_ground_surface_velocity(mean_altitude: float, elevation: float = 0, inclination: float = 0, latitude: float = 0) → float[source]

Fast computation of ground surface velocity (relative to the rotating Earth’s surface) assuming a circular orbit around a spherical Earth (using the mean Earth radius).

Parameters:
  • mean_altitude (float) – Orbit mean altitude (meters) above the mean Earth radius.

  • elevation (float) – Surface elevation (meters) above the mean Earth radius at which to project the ground point.

  • inclination (float) – Orbit inclination (degrees).

  • latitude (float) – Surface latitude (degrees) at which to evaluate the ground velocity.

Returns:

Ground surface velocity (meters/second), relative to the rotating Earth.

Return type:

float

tatc.utils.compute_vnb_frame(orbit_track: Geocentric) → tuple[npt.NDArray, npt.NDArray, npt.NDArray][source]

Computes the unit vectors of a satellite’s VNB (velocity, normal, binormal) frame: along its inertial velocity (V), normal to its orbit plane (N, along the angular momentum), and completing the right-handed frame (B, V x N), which coincides with the radial direction only for a circular orbit.

Parameters:

orbit_track (skyfield.positionlib.Geocentric) – The satellite orbit track (inertial position and velocity).

Returns:

the V, N, and B unit vectors (inertial, shape (3, …))

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_argument_of_latitude(position: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], velocity: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → float | ndarray[tuple[int, ...], dtype[float64]][source]

Computes the argument of latitude (degrees, from 0 to 360): the angle in the orbit plane from the ascending node to the satellite, in the direction of motion (0 at the ascending node, 90 at the northernmost point, 180 at the descending node, and 270 at the southernmost point).

Parameters:
  • position (numpy.typing.ArrayLike) – Inertial position(s), with shape (3,) or (3, N).

  • velocity (numpy.typing.ArrayLike) – Inertial velocity(ies), with shape (3,) or (3, N).

Returns:

the argument(s) of latitude (degrees)

Return type:

float | numpy.typing.NDArray[numpy.float64]

tatc.utils.compute_ascending_argument_of_latitude(latitude: float, altitude: float, inclination: float) → float[source]

Computes the argument of latitude (degrees, from 0 to 360) at which a circular orbit, ascending, passes over a geodetic latitude.

Parameters:
  • latitude (float) – The geodetic latitude (degrees) of the satellite.

  • altitude (float) – The satellite’s altitude (meters).

  • inclination (float) – The orbit’s inclination (degrees).

Returns:

The argument of latitude (degrees, from 0 to 360).

Return type:

float

Raises:

ValueError – If the orbit does not reach the latitude.

tatc.utils.compute_j2_raan_rate(semimajor_axis: float, inclination: float, eccentricity: float) → float[source]

Fast computation of the secular precession rate of the right ascension of the ascending node (nodal regression) due to Earth’s J2 oblateness perturbation. The rate is negative (westward regression) for prograde orbits (inclination < 90 degrees), zero for polar orbits (cos(90) = 0), and positive for retrograde orbits. Sun-synchronous orbits are defined by choosing an inclination that makes this rate equal to the Earth’s mean motion around the Sun (about 360/365.2422 degrees/day).

Parameters:
  • semimajor_axis (float) – Orbit semimajor axis (meters).

  • inclination (float) – Orbit inclination (degrees).

  • eccentricity (float) – Orbit eccentricity.

Returns:

The right ascension of ascending node precession rate (degrees/second).

Return type:

float

tatc.utils.compute_j2_aop_rate(semimajor_axis: float, inclination: float, eccentricity: float) → float[source]

Fast computation of the secular precession rate of the argument of periapsis due to Earth’s J2 oblateness perturbation. The rate is positive below the critical inclination (~63.43 degrees, where 5*cos^2(inclination) - 1 = 0), negative above it, and exactly zero at the critical inclination itself. Molniya-type orbits use this critical inclination specifically so their periapsis (and apoapsis) location does not drift over time.

Parameters:
  • semimajor_axis (float) – Orbit semimajor axis (meters).

  • inclination (float) – Orbit inclination (degrees).

  • eccentricity (float) – Orbit eccentricity.

Returns:

The argument of periapsis rate (degrees/second).

Return type:

float

tatc.utils.compute_j2_mean_motion_rate(semimajor_axis: float, inclination: float, eccentricity: float) → float[source]

Fast computation of the secular correction to mean anomaly’s rate of advance (beyond the unperturbed two-body mean motion) due to Earth’s J2 oblateness perturbation. Unlike the argument of periapsis rate, this correction is generally nonzero even at the critical inclination (~63.43 degrees), since its trigonometric factor (3*cos^2(inclination) - 1) only vanishes near ~54.7 degrees, not ~63.43 degrees. The true (“anomalistic”) mean motion is the unperturbed mean motion plus this correction; the anomalistic period (time from periapsis to periapsis) is 360 degrees divided by that sum, rather than by the unperturbed mean motion alone.

Parameters:
  • semimajor_axis (float) – Orbit semimajor axis (meters).

  • inclination (float) – Orbit inclination (degrees).

  • eccentricity (float) – Orbit eccentricity.

Returns:

The correction to the mean anomaly rate (degrees/second).

Return type:

float

tatc.utils.align_element_switches(satellites: list[Satellite], tolerance: timedelta = datetime.timedelta(seconds=600), shared_only: bool = True) → list[Satellite][source]

Aligns the times at which the satellites’ general perturbations (GP) orbits switch from one element to the next (see GeneralPerturbationsOrbit.element_switch_times), so that satellites whose elements are published together, as for a formation or a constellation, switch at common times.

By default, each satellite switches elements midway between its own consecutive epochs. When the satellites’ elements are published at slightly different times (for example, 20 s apart), for that long after each switch their positions come from elements of different epochs, whose errors no longer cancel, so their relative positions jump by up to the difference between successive elements.

The satellites’ epochs are grouped into publication events, each of epochs within tolerance of the next, and switches are placed midway between the mean epochs of consecutive events. Each satellite uses its latest element in each event and switches at the common time between the events of its consecutive elements (if it has no element in the events between, at the latest common time). With shared_only, only the events in which every satellite has an element are used, so the satellites always use elements of the same event, at the cost of using older elements when one satellite lacks an element in an event; otherwise, every event is used. Elements that are not used are removed.

Only satellites whose orbits have more than one GP element take part; the others are returned unchanged.

Parameters:
  • satellites (list[Satellite]) – The satellites.

  • tolerance (datetime.timedelta) – The maximum difference between the epochs of a publication event.

  • shared_only (bool) – True, to use only the publication events in which every satellite has an element.

Returns:

copies of the satellites, with aligned element switch

times (or unchanged, if they do not take part)

Return type:

list[Satellite]

Raises:

ValueError – if a publication event spans more than tolerance (as when epochs are spread through time rather than published together), if the mean epochs of consecutive events used are not more than twice tolerance apart, or if, with shared_only, no event is shared by every satellite.

tatc.utils.compute_max_access_time(altitude: float, min_elevation_angle: float) → float[source]

Fast computation of maximum access time to observe a point.

Parameters:
  • altitude (float) – Orbit altitude (meters).

  • min_elevation_angle (float) – Minimum elevation angle (degrees) for observation.

Returns:

The maximum access time (seconds) for observation.

Return type:

float

tatc.utils.compute_max_transit_time(mean_altitude: float, inclination: float, along_track: float) → float[source]

Fast computation of the maximum (conservative, worst-case) transit time to cover a specified along-track distance, using the slowest ground track velocity attained over the orbit, which occurs at the orbit’s extreme latitude (min(inclination, 180 - inclination)), not the equator.

Parameters:
  • mean_altitude (float) – The mean orbit altitude (meters) above WGS 84 datum.

  • inclination (float) – The orbit inclination (degrees).

  • along_track (float) – The along track distance (meters) observed during access.

Returns:

The maximum access time (seconds) to traverse the along track distance.

Return type:

float

tatc.utils.compute_min_along_track_distance(mean_altitude: float, inclination: float, access_time: float) → float[source]

Fast computation of the minimum (conservative, worst-case) along-track distance observed in a specified access time, using the slowest ground track velocity attained over the orbit, which occurs at the orbit’s extreme latitude (min(inclination, 180 - inclination)), not the equator. This is the inverse of compute_max_transit_time.

Parameters:
  • mean_altitude (float) – The mean orbit altitude (meters) above WGS 84 datum.

  • inclination (float) – The orbit inclination (degrees).

  • access_time (float) – The access time (seconds) during observation.

Returns:

The minimum along track distance (meters) observed during the access time.

Return type:

float

tatc.utils.compute_along_track_field_of_view(mean_altitude: float, time_step: float, inclination: float, latitude: float | None = None, eccentricity: float = 0) → float[source]

Compute an along-track field of view tailored to a time step: the angle subtended at nadir (from the satellite’s height above the WGS 84 ellipsoid) by the distance the ground track advances, relative to the rotating Earth, in one time step. The footprints of an instrument with this along-track field of view, at consecutive time steps, tile the ground track, so that the field of view represents the integration over the time step.

The ground track velocity varies with latitude by a few percent, as the Earth’s rotation adds to the motion of a retrograde orbit (such as a sun-synchronous orbit) and subtracts from that of a prograde orbit. By default, the fastest ground track velocity over the orbit is used, with the satellite at its lowest height above the ellipsoid (above the equator, where the ellipsoid’s radius is greatest, about 7 km below the mean altitude) and the ground track advancing over the ellipsoid’s greatest radius. For an eccentric orbit, the angle and velocity are evaluated at perigee, where the footprint is shortest relative to the ground track’s advance. Together, these make footprints tile without gaps over the whole orbit.

Parameters:
  • mean_altitude (float) – The mean orbit altitude (meters) above the mean Earth radius.

  • time_step (float) – The time step (seconds).

  • inclination (float) – The orbit inclination (degrees).

  • latitude (float | None) – The geodetic latitude (degrees) at which to evaluate the ground track velocity and the height above the ellipsoid, or None to use the fastest ground track velocity and lowest height over the orbit.

  • eccentricity (float) – The orbit eccentricity.

Returns:

The along-track field of view (degrees).

Return type:

float

tatc.utils.project_polygon_to_elevation(polygon: Polygon, elevation: float) → Polygon[source]
tatc.utils.project_polygon_to_elevation(polygon: MultiPolygon, elevation: float) → MultiPolygon

Assigns a fixed z-coordinate (elevation) to every coordinate of a polygon or multipolygon, including exterior and interior (hole) rings. Any existing z-coordinate is overwritten, not offset.

Parameters:
  • polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon) – The polygon to project.

  • elevation (float) – The elevation (meters) above the WGS 84 geoid to assign to every coordinate.

Returns:

The projected polygon, matching the input type.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

tatc.utils.split_polygon(polygon: Polygon | MultiPolygon) → Polygon | MultiPolygon[source]

Splits a Polygon into a MultiPolygon if it crosses the anti-meridian (180 degrees longitude), exceeds the north pole (90 degrees latitude), or exceeds the south pole (-90 degrees latitude). The anti-meridian may be crossed either by a jump between adjacent vertices (e.g. from 170 to -170 degrees) or by coordinates beyond +/-180 degrees (e.g. from 170 to 190 degrees). Note: this function only supports polygons that span LESS than 360 degrees longitude, other than polar caps (encircling a pole) and polygons spanning exactly -180 to 180 degrees. Operates on (longitude, latitude) only: any z-dimension on the input is discarded. Use project_polygon_to_elevation to add elevation back after splitting.

Parameters:

polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon) – The polygon to split.

Returns:

The split polygon.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

tatc.utils.normalize_geometry(geometry: Polygon | MultiPolygon | GeoDataFrame) → GeoDataFrame[source]

Normalize geometry to a GeoDataFrame with antimeridian wrapping.

Parameters:

| (geometry (shapely.geometry.Polygon | shapely.geometry.MultiPolygon) – geopandas.GeoDataFrame): The geometry to normalize.

Returns:

The normalized geometry.

Return type:

geopandas.GeoDataFrame

tatc.utils.hash_geometry(geometry: BaseGeometry) → str[source]

Computes a compact hash of a geometry, to identify it (for example, the region of interest of an observation) without storing it: the first 16 hexadecimal digits (64 bits) of the BLAKE2b digest of its normalized well-known binary (little-endian, with z coordinates, which are zero if missing). Geometries with the same normalized coordinates have the same hash, regardless of the order of their vertices, rings, or parts, and a geometry without z coordinates has the same hash as at zero elevation.

Parameters:

geometry (shapely.geometry.base.BaseGeometry) – The geometry.

Returns:

The hash, as 16 hexadecimal digits.

Return type:

str

tatc.utils.geodesic_distance(longitude_1: float, latitude_1: float, longitude_2: float, latitude_2: float) → float[source]

Computes the geodesic surface distance between two longitude/latitude points on the WGS 84 ellipsoid: the length of the shortest path between them that stays on the ellipsoid surface. Unlike a longitude/latitude-based (planar) distance, this accounts for the Earth’s oblateness and the convergence of meridians toward the poles, so it remains accurate at any latitude or longitude separation (including antipodal-ish or antimeridian-spanning point pairs).

Parameters:
  • longitude_1 (float) – Longitude (degrees) of the first point.

  • latitude_1 (float) – Latitude (degrees) of the first point.

  • longitude_2 (float) – Longitude (degrees) of the second point.

  • latitude_2 (float) – Latitude (degrees) of the second point.

Returns:

The geodesic distance (meters) between the two points.

Return type:

float

tatc.utils.geodesic_destination(longitude: float, latitude: float, azimuth: float, distance: float) → tuple[float, float][source]

Computes the longitude/latitude reached by traveling a specified geodesic distance from a starting point at a specified initial azimuth, on the WGS 84 ellipsoid.

Parameters:
  • longitude (float) – Longitude (degrees) of the starting point.

  • latitude (float) – Latitude (degrees) of the starting point.

  • azimuth (float) – Initial azimuth (degrees, clockwise from north) of travel.

  • distance (float) – Geodesic distance (meters) to travel.

Returns:

The destination (longitude, latitude), in degrees.

Return type:

tuple[float, float]

tatc.utils.get_planar_bounds(mask: Polygon | MultiPolygon | None) → tuple[float, float, float, float][source]

Generates a tuple of bounds for a polygon mask.

Known limitation: this method assumes mask lies on the planar (non-antimeridian-crossing) longitude domain. A mask crossing the antimeridian with longitude below -180 (e.g. bounds spanning -190 to -180, representing the same region as 170 to 180) only has its max_longitude corrected to 180; min_longitude is left unadjusted, so the resulting bounds do not coherently describe such a mask. Fully supporting antimeridian-crossing masks can be achieved by pre-processing the geometry (e.g. via split_polygon).

Parameters:

mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – Geometric shape using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

Returns:

min longitude (degrees),

min latitude (degrees), max longitude (degrees), max latitude (degrees)

Return type:

tuple[float, float, float, float]

tatc.utils.to_datetime64_ns(value: datetime) → datetime64[source]
tatc.utils.to_datetime64_ns(value: list[datetime] | ndarray[tuple[int, ...], dtype[datetime64]]) → ndarray[tuple[int, ...], dtype[datetime64]]
tatc.utils.to_datetime64_ns(value: Time) → datetime64 | ndarray[tuple[int, ...], dtype[datetime64]]

Converts a datetime (or a list/array of datetimes, or a Skyfield time) to numpy datetime64[ns]. Timezone-aware datetimes are normalized to naive UTC first because numpy deprecates implicit timezone-aware conversion.

A Skyfield Time is converted from its UTC calendar fields in vectorized form, which is much faster for large arrays than converting each time to a Python datetime (e.g. via Time.utc_datetime). Times within a leap second carry over into the following minute.

Parameters:

value (datetime | list[datetime] | npt.NDArray[np.datetime64] | Time) – the time(s) to convert

Returns:

the converted datetime64 value(s)

Return type:

np.datetime64 | npt.NDArray[np.datetime64]

tatc.utils.zero_pad(object_name: str, max_number: int, current_number: int) → str[source]

Appends a zero-padded number to an object name to create a unique, sortable label for a member of a numbered collection (e.g. a satellite in a constellation). The padding width is derived from max_number so every generated label consumes the same number of characters, which keeps lexicographic (string) sort order consistent with numeric order.

Note

If current_number requires more digits than max_number, it is left at its natural width rather than truncated, so the fixed-width guarantee no longer holds for that entry.

Parameters:
  • object_name (str) – Base name to prefix the generated label (e.g. a constellation name).

  • max_number (int) – The largest number that will be padded; determines the padding width.

  • current_number (int) – The number to zero-pad and append to object_name.

Returns:

object_name, a single space, and current_number zero-padded to the width of max_number.

Return type:

str

tatc.utils.altitude_to_pressure(altitude: float) → float[source]

Fast computation of atmospheric pressure at a specified altitude, using the U.S. Standard Atmosphere (1976) model. Inputs outside the model’s valid range (0 to 86 km) saturate to the pressure at the nearest bound.

Parameters:

altitude (float) – Altitude (meters) above mean sea level.

Returns:

Atmospheric pressure (Pa). Divide by 100 to convert to the

hPa (millibar) units common in atmospheric science.

Return type:

float

tatc.utils.pressure_to_altitude(pressure: float) → float[source]

Fast computation of altitude at a specified atmospheric pressure, using the U.S. Standard Atmosphere (1976) model. This is the inverse of altitude_to_pressure; inputs outside the model’s valid range (down to the pressure at 86 km) saturate to the altitude at the nearest bound.

Parameters:

pressure (float) – Atmospheric pressure (Pa). Multiply hPa (millibar) values, common in atmospheric science, by 100 to convert to Pa.

Returns:

Altitude (meters) above mean sea level.

Return type:

float

tatc.utils.geodetic_to_rectangular(longitude: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], latitude: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], elevation: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 0) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Converts WGS 84 geodetic coordinates to Earth-fixed (ITRS) rectangular coordinates, vectorized across positions.

Parameters:
  • longitude (numpy.typing.ArrayLike) – The geodetic longitudes (degrees).

  • latitude (numpy.typing.ArrayLike) – The geodetic latitudes (degrees).

  • elevation (numpy.typing.ArrayLike) – The elevations (meters) above the WGS 84 ellipsoid.

Returns:

the positions (meters, shape (3, …))

Return type:

numpy.typing.NDArray

tatc.utils.rectangular_to_geodetic(position: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Converts Earth-fixed (ITRS) rectangular coordinates to WGS 84 geodetic coordinates, vectorized across positions, by fixed-point iteration on the geodetic latitude (stable at the poles, and converged to well below a micrometer for positions near the Earth’s surface).

Parameters:

position (numpy.typing.ArrayLike) – The positions (meters, shape (3, …)).

Returns:

the geodetic longitudes (degrees), latitudes (degrees), and altitudes (meters)

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_ellipsoid_intersection(position: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], direction: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], elevation: float = 0) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Computes the first intersections of rays with the WGS 84 ellipsoid, with its semi-axes extended by an elevation (which approximates the surface at that elevation above the ellipsoid), vectorized across rays.

Parameters:
  • position (numpy.typing.ArrayLike) – The rays’ origins (meters, Earth-fixed, shape (3, N)).

  • direction (numpy.typing.ArrayLike) – The rays’ directions (Earth-fixed, shape (3, N)).

  • elevation (float) – The elevation (meters) above the WGS 84 ellipsoid.

Returns:

the intersection

points (meters, shape (3, N); the origins for rays that miss) and whether each ray intersects the ellipsoid

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray]

tatc.utils.compute_tangent_point(position: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], direction: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], iterations: int = 3) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Computes the tangent point of each line position + s * direction: its point of minimum WGS 84 geodetic altitude, where the line is tangent to the surface of constant geodetic altitude (as for the line of sight of a radio occultation or a limb sounder). The tangent point differs from the line’s closest approach to the Earth’s center by up to about 20 km horizontally at middle latitudes, but by only meters in altitude.

Starts from the closest approach to the Earth’s center and refines the tangent altitude iterations times (see _find_tangent_distance); three refinements converge to well below a millimeter in altitude.

Parameters:
  • position (numpy.typing.ArrayLike) – Points on the lines (meters, Earth-fixed, shape (3, N)).

  • direction (numpy.typing.ArrayLike) – The lines’ directions (Earth-fixed, shape (3, N)).

  • iterations (int) – The number of refinements of the tangent altitude.

Returns:

the tangent points (meters, Earth-fixed, shape (3, N))

Return type:

numpy.typing.NDArray

tatc.utils.compute_radar_beam_height(slant_range: float, elevation_angle: float, station_height: float = 0) → float[source]

Fast computation of the radar beam height at a specified slant range along a beam at a specified elevation angle, using the standard-atmosphere “4/3 Earth radius” refraction approximation (a spherical Earth with an effective radius scaled by constants.EFFECTIVE_EARTH_RADIUS_FACTOR).

Parameters:
  • slant_range (float) – Slant range (meters) along the radar beam.

  • elevation_angle (float) – Radar beam elevation angle (degrees) above local horizontal.

  • station_height (float) – Radar antenna height (meters).

Returns:

The beam height (meters), in the same vertical reference as station_height.

Return type:

float

tatc.utils.compute_radar_ground_range(slant_range: float, elevation_angle: float, station_height: float = 0) → float[source]

Fast computation of the ground (surface) range to the point reached by a specified slant range along a radar beam at a specified elevation angle, using the standard-atmosphere “4/3 Earth radius” refraction approximation.

Parameters:
  • slant_range (float) – Slant range (meters) along the radar beam.

  • elevation_angle (float) – Radar beam elevation angle (degrees) above local horizontal.

  • station_height (float) – Radar antenna height (meters).

Returns:

The ground range (meters), measured along the Earth’s surface from the station, to the point reached by slant_range.

Return type:

float

tatc.utils.compute_radar_slant_range(elevation_angle: float, target_height: float, station_height: float = 0) → float[source]

Fast computation of the slant range at which a radar beam at a specified elevation angle reaches a specified target height, using the standard-atmosphere “4/3 Earth radius” refraction approximation. This is the inverse of compute_radar_beam_height.

Parameters:
  • elevation_angle (float) – Radar beam elevation angle (degrees) above local horizontal.

  • target_height (float) – Target height (meters), in the same vertical reference as station_height.

  • station_height (float) – Radar antenna height (meters).

Returns:

The slant range (meters) at which the beam reaches target_height, or numpy.nan if there is no real, non-negative solution. A beam departing at or above local horizontal (elevation_angle >= 0) only climbs with increasing range under this model, so target_height < station_height always yields numpy.nan; target_height == station_height yields 0. A beam departing below local horizontal (elevation_angle < 0) first descends and then climbs, so it can cross a height twice; this returns the farther (climbing) crossing.

Return type:

float

tatc.utils.compute_radar_ground_range_bounds(min_elevation_angle: float, max_elevation_angle: float, max_range: float, target_elevation: float, station_elevation: float = 0) → tuple[float, float] | None[source]

Computes the ground-range annulus (meters) within which a ground-based radar can detect a target at a specified elevation, using the standard-atmosphere “4/3 Earth radius” refraction approximation.

The inner bound is the ground range at which the highest scanned elevation angle first reaches target_elevation (closer in, no scanned angle has climbed that high – an overhead “cone of silence”). The outer bound is the ground range at which the lowest scanned elevation angle reaches target_elevation, capped by max_range: if the lowest tilt reaches target_elevation within max_range, the beam has overshot the target height before running out of range.

A target at or below station_elevation is observable only if the lowest elevation angle is below local horizontal: such a beam first descends and then climbs, so it passes below the target between its descending and climbing crossings of target_elevation, which become the inner and outer bounds (higher beams, assumed at or above local horizontal, always pass above the target). Otherwise, every beam stays above the antenna and the target is not observable.

Parameters:
  • min_elevation_angle (float) – Lowest scanned elevation angle (degrees).

  • max_elevation_angle (float) – Highest scanned elevation angle (degrees).

  • max_range (float) – Maximum unambiguous slant range (meters).

  • target_elevation (float) – Target height (meters), in the same vertical reference as station_elevation.

  • station_elevation (float) – Radar antenna height (meters).

Returns:

The (inner_ground_range, outer_ground_range) bounds (meters), or None if there is no ground range at which the target is observable (including the degenerate case min_elevation_angle == max_elevation_angle).

Return type:

tuple[float, float] | None

tatc.utils.compute_terrain_elevation_angle(ground_distance: float, terrain_elevation: float, station_elevation: float = 0, effective_earth_radius_factor: float = 1.3333333333333333) → float[source]

Fast computation of the curvature-corrected elevation angle, as seen from a ground-based station, to a terrain point at a specified ground distance and elevation. Uses the standard-atmosphere “4/3 Earth radius” refraction approximation (the same effective-Earth-radius model used elsewhere in this module) to account for both the Earth’s curvature and atmospheric refraction bending the line of sight: this is the small-angle “curvature drop” correction standard to radio/radar line-of-sight terrain analysis, distinct from (and simpler than) the exact beam-height geometry used by compute_radar_beam_height, since here the target (a terrain point) is given directly by its ground distance and elevation, not by a slant range and elevation angle.

Parameters:
  • ground_distance (float) – Ground (surface) distance (meters) to the terrain point.

  • terrain_elevation (float) – Elevation (meters) of the terrain point, in the same vertical reference as station_elevation.

  • station_elevation (float) – Elevation (meters) of the station (antenna).

  • effective_earth_radius_factor (float) – The ratio of the effective Earth radius to the mean Earth radius, accounting for refraction: 4/3 for radio waves in a standard atmosphere (the default), or 1 for straight lines of sight (without refraction).

Returns:

The elevation angle (degrees) to the terrain point, as seen from the station; positive above local horizontal, negative below.

Return type:

float

tatc.utils.compute_radar_footprint(longitude: float, latitude: float, inner_ground_range: float, outer_ground_range: float, elevation: float = 0) → Polygon | MultiPolygon[source]

Builds a ground-based radar coverage footprint (a disk, or an annulus if inner_ground_range is positive) centered on the specified longitude/latitude, by reprojecting to a distance-preserving CRS, buffering by the ground ranges, and reprojecting back.

Parameters:
  • longitude (float) – Longitude (degrees) of the radar station.

  • latitude (float) – Latitude (degrees) of the radar station.

  • inner_ground_range (float) – The inner ground range (meters) of the footprint annulus; 0 for a full disk.

  • outer_ground_range (float) – The outer ground range (meters) of the footprint.

  • elevation (float) – The elevation (meters) at which to project the footprint.

Returns:

The radar footprint.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

tatc.utils.compute_radar_footprint_profile(longitude: float, latitude: float, azimuths: Iterable[float], outer_ground_ranges: Iterable[float], inner_ground_range: float | Iterable[float], elevation: float = 0) → Polygon | MultiPolygon[source]

Builds an azimuthally irregular ground-based radar coverage footprint from a sampled outer-boundary profile (e.g. reflecting per-azimuth terrain blockage), optionally subtracting an inner hole: either a uniform circle (e.g. the overhead “cone of silence” for a target above the antenna, governed by the antenna’s maximum scan elevation angle rather than terrain) or a sampled inner-boundary profile (e.g. for a target below the antenna, where the inner bound depends on the lowest usable elevation angle and therefore on terrain). The footprint is built continuously about the station’s longitude (see _unwrap_longitudes), and then split along the anti-meridian and poles (see split_polygon).

Parameters:
  • longitude (float) – Longitude (degrees) of the radar station.

  • latitude (float) – Latitude (degrees) of the radar station.

  • azimuths (Iterable[float]) – Azimuth samples (degrees, clockwise from north), in increasing order, spanning one full revolution.

  • outer_ground_ranges (Iterable[float]) – The outer ground range (meters) of the footprint at each corresponding azimuth.

  • inner_ground_range (float | Iterable[float]) – The inner ground range (meters) of the footprint annulus, either uniform (0 for no hole) or at each corresponding azimuth.

  • elevation (float) – The elevation (meters) at which to project the footprint.

Returns:

The radar footprint.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon