Utility Functions

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

Converts mean anomaly to true anomaly.

Parameters:

  • mean_anomaly (float) – The mean anomaly (degrees).

  • true_anomaly (float) – The orbit eccentricity.

Returns:

The true anomaly (degrees).

Return type:

float

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

Converts true anomaly to mean anomaly.

Parameters:

  • true_anomaly (float) – The true anomaly (degrees).

  • eccentricity (float) – The orbit eccentricity.

Returns:

The 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.

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 conversion from swath width to field of regard.

Parameters:

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

  • swath_width (float) – Observation diameter (meters) at specified elevation.

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

Returns:

The field of regard (degrees).

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 conversion from swath width to field of view considering off-nadir pointing.

Parameters:

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

  • swath_width (float) – Observation diameter (meters) at specified elevation.

  • look_angle (float) – Off-nadir look angle (degrees) to observation center.

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

Returns:

The field of view (degrees).

Return type:

float

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

Fast conversion from field of regard to swath width.

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 observation diameter (meters) 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[source]

Buffers a ground track point to create a footprint.

Parameters:

  • geometry (shapely.Geometry) – The geometry to buffer.

  • origin_crs (str) – The origin coordinate reference system (CRS).

  • buffer_crs (str) – The buffering coordinate reference system (CRS).

  • 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:

Union[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) → Geometry | List[Geometry][source]

Compute the instanteous instrument footprint.

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.

  • pitch_angle (float) – The fore/aft look angle (degrees); right-hand rotation about orbit normal vector.

  • roll_angle (float) – The left/right look angle (degrees); right-hand rotation about orbit velocity vector.

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

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

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

Returns:

The instrument footprint(s).

Return type:

Union[shapely.Geometry, List[shapely.Geometry]

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_orbit_period(altitude: float) → float[source]

Fast computation of approximate orbital period.

Parameters:

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

Returns:

The orbital period (seconds).

Return type:

float

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) – Altitude (meters) above WGS 84 datum for the observing instrument.

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

Returns:

The maximum access time (seconds) for observation.

Return type:

float

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

Projects a polygon to a specified elevation (z-coordinate).

Parameters:

  • polygon (Polygon or MultiPolygon) – The polygon to project.

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

Returns:

The projected polygon.

Return type:

Polygon or 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). Note: this function only supports polygons that span LESS than 360 degrees longitude.

Parameters:

polygon (Polygon or MultiPolygon) – The polygon to split.

Returns:

The split polygon.

Return type:

Polygon, or MultiPolygon

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

Normalize geometry to a GeoDataFrame with antimeridian wrapping.

Parameters:

geometry (geopandas.GeoDataFrame, geopandas.GeoSeries, Polygon, or MultiPolygon) – The geometry to normalize.

Returns:

The normalized geometry.

Return type:

geopandas.GeoDataFrame