Skip to content

location

location #

Candidate capture places: the points a survey polygon could be captured from.

The polygon's longitudes are first made continuous across the antimeridian, the polygon is sampled — a grid inside it (locations_area) or a walk along its edges (locations_perimeter) — and the samples wrap back to [-180, 180].

locations_area(bounds, resolution_meters=1.0) #

Generate a grid of locations within the given polygon bounds.

The grid is a plain latitude/longitude mesh, so it distorts at high latitudes where longitude degrees are shorter; the resolution holds at the centre latitude of the bounds.

Parameters:

Name Type Description Default
bounds Array[Location]

The polygon's vertices, at least three, in winding order (either direction).

required
resolution_meters float

Spacing between grid points in meters. Smaller values produce more points but take longer to compute.

1.0

Returns:

Type Description
Array[Location]

The grid points inside the polygon, longitudes in [-180, 180] and no

Array[Location]

altitude — empty when the polygon is small relative to the resolution.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/location.py
def locations_area(
    bounds: cg.Array[cg.Location],
    resolution_meters: float = 1.0,
) -> cg.Array[cg.Location]:
    """Generate a grid of locations within the given polygon bounds.

    The grid is a plain latitude/longitude mesh, so it distorts at high
    latitudes where longitude degrees are shorter; the resolution holds at
    the centre latitude of the bounds.

    Args:
        bounds: The polygon's vertices, at least three, in winding order
            (either direction).
        resolution_meters: Spacing between grid points in meters. Smaller
            values produce more points but take longer to compute.

    Returns:
        The grid points inside the polygon, longitudes in [-180, 180] and no
        altitude — empty when the polygon is small relative to the resolution.
    """
    latitudes = np.array(bounds.latitude)
    longitudes = _continuous(np.array(bounds.longitude), np.min(np.array(bounds.longitude)))
    polygon = shapely.Polygon(np.column_stack([longitudes, latitudes]))

    min_lat, max_lat = np.min(latitudes), np.max(latitudes)
    min_lon, max_lon = np.min(longitudes), np.max(longitudes)
    lat_meters = (max_lat - min_lat) * METERS_PER_DEGREE
    lon_meters = (
        (max_lon - min_lon) * METERS_PER_DEGREE * np.cos(np.radians((max_lat + min_lat) / 2))
    )

    grid_lons, grid_lats = np.meshgrid(
        np.linspace(min_lon, max_lon, int(np.round(lon_meters / resolution_meters))),
        np.linspace(min_lat, max_lat, int(np.round(lat_meters / resolution_meters))),
    )
    inside = shapely.contains_xy(polygon, grid_lons.ravel(), grid_lats.ravel())
    return _locations(grid_lons.ravel()[inside], grid_lats.ravel()[inside])

locations_perimeter(bounds, resolution_meters=1.0) #

Generate evenly-spaced locations along the perimeter of a polygon.

Each edge is interpolated linearly in latitude/longitude — close to the geodesic for short edges — and the polygon is closed from the last vertex back to the first.

Parameters:

Name Type Description Default
bounds Array[Location]

The polygon's vertices, at least three, in winding order (either direction).

required
resolution_meters float

Target spacing between points in meters. Actual spacing varies slightly so every vertex is included.

1.0

Returns:

Type Description
Array[Location]

The points along the edges in order from the first vertex, each edge

Array[Location]

contributing its start vertex but not its end. Longitudes are in

Array[Location]

[-180, 180] and no altitude is set.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/location.py
def locations_perimeter(
    bounds: cg.Array[cg.Location],
    resolution_meters: float = 1.0,
) -> cg.Array[cg.Location]:
    """Generate evenly-spaced locations along the perimeter of a polygon.

    Each edge is interpolated linearly in latitude/longitude — close to the
    geodesic for short edges — and the polygon is closed from the last vertex
    back to the first.

    Args:
        bounds: The polygon's vertices, at least three, in winding order
            (either direction).
        resolution_meters: Target spacing between points in meters. Actual
            spacing varies slightly so every vertex is included.

    Returns:
        The points along the edges in order from the first vertex, each edge
        contributing its start vertex but not its end. Longitudes are in
        [-180, 180] and no altitude is set.
    """
    latitudes = np.array(bounds.latitude)
    longitudes = _continuous(np.array(bounds.longitude), np.min(np.array(bounds.longitude)))
    vertices = [
        cg.Location(latitude=float(lat), longitude=float(lon))
        for lon, lat in zip(longitudes, latitudes, strict=True)
    ]

    edge_lons: list[np.ndarray] = []
    edge_lats: list[np.ndarray] = []
    for start, end in zip(vertices, [*vertices[1:], vertices[0]], strict=True):
        steps = max(2, round(_METERS(start, end) / resolution_meters))
        edge_lons.append(np.linspace(start.longitude, end.longitude, steps, endpoint=False))
        edge_lats.append(np.linspace(start.latitude, end.latitude, steps, endpoint=False))
    return _locations(np.concatenate(edge_lons), np.concatenate(edge_lats))