Add surface observation

CHANGELOG.md

@@ -2,13 +2,14 @@
 
 ## 3.6.0
 
-Added new observing capabilities for limb sounding, ground-based radar, and regions (polygons), with support for shapely points. Changed how general perturbations orbits are propagated, with options to model orbits maintained on a repeat ground track. Also changed the tangent point for GNSS radio occultation (RO) and limb sounding to the point of minimum WGS 84 geodetic altitude along the line of sight.
+Added new observing capabilities for limb sounding, ground-based radar, fixed surface platforms, and regions (polygons), with support for shapely points. Changed how general perturbations orbits are propagated, with options to model orbits maintained on a repeat ground track. Also changed the tangent point for GNSS radio occultation (RO) and limb sounding to the point of minimum WGS 84 geodetic altitude along the line of sight.
 
 Added:
  - Analysis method `collect_limb_observations` (with enumeration `ScanDirection`) for limb sounding observations from periodic scans at a constant angular rate.
  - Analysis method `collect_space_observations` for the periods when satellites can observe other satellites (as by a sensor or a radio frequency link), subject to slant range limits and Earth occlusion (a minimum WGS 84 geodetic altitude of the line of sight). Each observation records the lines of sight at its start and end as its geometry.
  - Object schemas `RadarStation` (with `RadarBand` and `RadarStation.from_band`) and `TerrainMask`, and analysis methods `collect_radar_track` and `compute_radar_track`, for ground-based radar coverage. `AllSurfaceObjects` includes `RadarStation`.
- - Module `preprocess` to derive inputs from external datasets, including terrain masks from Copernicus DEM data (`compute_terrain_mask`, `compute_terrain_mask_for_station`, `get_copernicus_dem_tile_urls`, and `sample_dem_elevation`), and gridded weights from GeoTIFF rasters (`read_raster_weights`).
+ - Object schema `SurfacePlatform` (included in `AllSurfaceObjects`) for instruments on platforms fixed above the Earth's surface, such as towers or tethered balloons, with a `heading` that orients their views, and analysis methods `collect_platform_track` and `compute_platform_track` for the static footprints of their `Instrument` and `PointedInstrument` views at a target elevation, either below the instruments (looking down) or above them (looking up, as at clouds), with views clipped to the horizon of the ground below (argument `ground_elevation` of the footprint and pixel methods) and to an optional `terrain_mask` (a `TerrainMask`, as for a `RadarStation`), with method `SurfacePlatform.compute_visible_region` for the region of a target above the instruments visible over them. Utility method `compute_static_track` gives a fixed position the form of an orbit track, from which instruments project their views as from a satellite.
+ - Module `preprocess` to derive inputs from external datasets, including terrain masks from Copernicus DEM data (`compute_terrain_mask`, `compute_terrain_mask_for_station`, `compute_terrain_mask_for_platform`, `get_copernicus_dem_tile_urls`, and `sample_dem_elevation`, with an `effective_earth_radius_factor` for refraction, also an argument of `compute_terrain_elevation_angle`), and gridded weights from GeoTIFF rasters (`read_raster_weights`).
  - Generation method `generate_points_random` for random points, uniform by area or weighted by a raster (for example, of population counts or densities), optionally within a mask, with a seed for reproducibility.
  - Analysis methods `collect_region_observations` and `collect_multi_region_observations` to collect the periods (start and end) when an instrument observes any part of a region (shapely `Polygon` or `MultiPolygon`), using the footprints of pointed and conical instruments and the field of regard of other instruments. Each observation records its swath (the part of the region swept by the footprint) as its geometry and identifies the region by the hash of its geometry (`target_hash`). Methods `aggregate_observations` and `reduce_observations` combine the swaths of a region into the part of it observed.
  - Analysis methods `compute_access_periods`, the periods when a satellite is in view of a point above a minimum elevation angle, and `compute_region_access_periods`, a conservative superset of the periods when an instrument's field of regard may observe any part of a region (for example, to cull analysis times).
@@ -50,6 +51,7 @@ Changed:
  - Fixed `SunSynchronousOrbit` to place the ascending node in local mean solar time and to keep the local time of its equator crossings constant as propagated.
  - Fixed `TrainConstellation` for long intervals between members, and `MolniyaOrbit` and `TundraOrbit` periods to repeat the ground track as propagated.
  - Fixed rectangular footprints of wide, elongated views.
+ - Fixed `PointedInstrument.compute_footprint_pixel_array` for a single-time (scalar) orbit track.
  - Fixed `split_polygon` for longitudes beyond 180 degrees, for polygons spanning -180 to 180 degrees of longitude, and for holes across the anti-meridian or around a pole (holes are now split like exteriors), and to drop degenerate (zero-area) parts left by repairing invalid polygons.
  - Fixed cached orbit computations for copies with changed fields, and orbits and satellites to be picklable after propagation.
  - Fixed numba-compiled utility methods (in `tatc.utils.orbital`, `observation`, `radar`, `atmosphere`, and `surface`) returning `nan` for integer inputs, which overflowed in compiled integer arithmetic (for example, `semimajor_axis_to_mean_motion(7000000)`): inputs are now converted to floats.

docs/api_reference/analysis/track.rst

@@ -28,3 +28,19 @@ Compute Ground Track
 Collect Ground Pixels
 ----------------------
 .. autofunction:: tatc.analysis.collect_ground_pixels
+
+Collect Platform Track
+----------------------
+.. autofunction:: tatc.analysis.collect_platform_track
+
+Compute Platform Track
+----------------------
+.. autofunction:: tatc.analysis.compute_platform_track
+
+Collect Radar Track
+-------------------
+.. autofunction:: tatc.analysis.collect_radar_track
+
+Compute Radar Track
+-------------------
+.. autofunction:: tatc.analysis.compute_radar_track

docs/api_reference/generation/index.rst

@@ -27,10 +27,9 @@ Random
 
 .. autofunction:: tatc.generation.generate_points_random
 
-Weights for random points can be read from a GeoTIFF raster (requires the
-optional `preprocess` dependencies, ``pip install tatc[preprocess]``):
-
-.. autofunction:: tatc.preprocess.read_raster_weights
+Weights for random points can be read from a GeoTIFF raster with
+:func:`tatc.preprocess.read_raster_weights` (requires the optional
+`preprocess` dependencies, ``pip install tatc[preprocess]``).
 
 Cells
 =====

docs/api_reference/index.rst

@@ -10,4 +10,5 @@ The following provide documentation on the Python API to TAT-C.
   schemas/index
   generation/index
   analysis/index
+  preprocess/index
   utils/index

docs/api_reference/preprocess/index.rst

@@ -0,0 +1,47 @@
+=======================
+Preprocessing Functions
+=======================
+
+Preprocessing functions derive TAT-C model inputs from external geospatial
+datasets. They require the optional `preprocess` dependencies
+(``pip install tatc[preprocess]``).
+
+Terrain Masks
+=============
+
+Terrain masks (:class:`tatc.schemas.TerrainMask`) for radar stations and
+surface platforms are derived by ray-tracing a digital elevation model (DEM),
+such as the public Copernicus DEM GLO-30.
+
+Copernicus DEM Tiles
+--------------------
+
+.. autofunction:: tatc.preprocess.get_copernicus_dem_tile_urls
+
+Sample DEM Elevation
+--------------------
+
+.. autofunction:: tatc.preprocess.sample_dem_elevation
+
+Compute Terrain Mask
+--------------------
+
+.. autofunction:: tatc.preprocess.compute_terrain_mask
+
+Compute Terrain Mask for Station
+--------------------------------
+
+.. autofunction:: tatc.preprocess.compute_terrain_mask_for_station
+
+Compute Terrain Mask for Platform
+---------------------------------
+
+.. autofunction:: tatc.preprocess.compute_terrain_mask_for_platform
+
+Rasters
+=======
+
+Read Raster Weights
+-------------------
+
+.. autofunction:: tatc.preprocess.read_raster_weights

docs/api_reference/schemas/surface.rst

@@ -12,3 +12,24 @@ Ground Station
 
 .. autopydantic_model:: tatc.schemas.GroundStation
   :members:
+
+Radar Station
+-------------
+
+.. autopydantic_model:: tatc.schemas.RadarStation
+  :members:
+
+.. autoclass:: tatc.schemas.RadarBand
+  :members:
+
+Surface Platform
+----------------
+
+.. autopydantic_model:: tatc.schemas.SurfacePlatform
+  :members:
+
+Terrain Mask
+------------
+
+.. autopydantic_model:: tatc.schemas.TerrainMask
+  :members:

docs/api_reference/utils/index.rst

@@ -24,8 +24,12 @@ Utility Functions
 
 .. autofunction:: tatc.utils.compute_projected_ray_position
 
+.. autofunction:: tatc.utils.compute_static_track
+
 .. autofunction:: tatc.utils.compute_view_tangents
 
+.. autofunction:: tatc.utils.compute_view_angles
+
 .. autofunction:: tatc.utils.compute_cone_and_azimuth
 
 .. autoclass:: tatc.utils.VelocityFrame
@@ -34,6 +38,9 @@ Utility Functions
 .. autoclass:: tatc.utils.NadirReference
   :members:
 
+.. autoclass:: tatc.utils.ViewGeometry
+  :members:
+
 .. autofunction:: tatc.utils.compute_field_of_regard
 
 .. autofunction:: tatc.utils.compute_min_elevation_angle
@@ -56,6 +63,8 @@ Utility Functions
 
 .. autofunction:: tatc.utils.compute_vnb_frame
 
+.. autofunction:: tatc.utils.compute_argument_of_latitude
+
 .. autofunction:: tatc.utils.compute_j2_raan_rate
 
 .. autofunction:: tatc.utils.compute_j2_aop_rate
@@ -80,6 +89,8 @@ Utility Functions
 
 .. autofunction:: tatc.utils.geodesic_distance
 
+.. autofunction:: tatc.utils.geodesic_destination
+
 .. autofunction:: tatc.utils.get_planar_bounds
 
 .. autofunction:: tatc.utils.to_datetime64_ns
@@ -97,3 +108,17 @@ Utility Functions
 .. autofunction:: tatc.utils.compute_ellipsoid_intersection
 
 .. autofunction:: tatc.utils.compute_tangent_point
+
+.. autofunction:: tatc.utils.compute_radar_beam_height
+
+.. autofunction:: tatc.utils.compute_radar_ground_range
+
+.. autofunction:: tatc.utils.compute_radar_slant_range
+
+.. autofunction:: tatc.utils.compute_radar_ground_range_bounds
+
+.. autofunction:: tatc.utils.compute_terrain_elevation_angle
+
+.. autofunction:: tatc.utils.compute_radar_footprint
+
+.. autofunction:: tatc.utils.compute_radar_footprint_profile