Waypoint

Waypoint class for flight planning with position, altitude, heading, and speed.

class Waypoint[source]

Bases: object

__init__(latitude, longitude, heading, altitude_msl=None, name=None, speed=None, delay=None, segment_type=None)[source]

Initialize a Waypoint object.

Parameters:

  • latitude (float) – Latitude in decimal degrees.

  • longitude (float) – Longitude in decimal degrees.

  • heading (float) – Heading in degrees relative to North.

  • altitude_msl (Union[Quantity, float, None], optional) – Altitude MSL in meters or as a pint Quantity. Defaults to None.

  • name (str, optional) – Name of the waypoint. Defaults to None.

  • speed (Union[Quantity, float, None], optional) – Speed override in m/s or as a pint Quantity. Used for the departing leg. Defaults to None.

  • delay (Union[Quantity, float, None], optional) – Loiter time at waypoint in seconds or as a pint Quantity. Defaults to None.

  • segment_type (str, optional) – Segment type label for the departing leg (e.g. “pattern”, “sampling”). Used by compute_flight_plan. Defaults to None.

offset_north_east(offset_north, offset_east)[source]

Return a new Waypoint translated by geodetic N/E offsets.

Parameters:

  • offset_north (Quantity | float) – Distance north (positive) or south (negative). Float interpreted as meters; or a pint Quantity with length units.

  • offset_east (Quantity | float) – Distance east (positive) or west (negative). Float interpreted as meters; or a pint Quantity with length units.

Return type:

Waypoint

Returns:

A new Waypoint at the translated position, preserving all other attributes.

to_dict()[source]

Convert the waypoint to a dictionary representation.

The returned dict round-trips through Waypoint.from_dict() and includes every field accepted by __init__. Quantity-valued fields (altitude_msl, speed, delay) are returned as pint.Quantity instances; for JSON-friendly output the caller is responsible for serialization.

Returns:

Dictionary with all eight Waypoint fields:

latitude, longitude, heading, altitude_msl, name, speed, delay, segment_type.

Return type:

Dict

classmethod from_dict(data)[source]

Reconstruct a Waypoint from a to_dict() dictionary.

Required keys are latitude, longitude, and heading. Optional keys (altitude_msl, name, speed, delay, segment_type) default to None if absent. This is the inverse of to_dict() and round-trips losslessly when the Quantity fields are preserved as pint.Quantity instances.

Parameters:

data (dict[Any, Any]) – Mapping produced by to_dict(), or a subset thereof.

Return type:

Waypoint

Returns:

A new Waypoint instance.

classmethod relative_to(anchor, *, bearing, distance, heading=None, altitude_msl=None, name=None, speed=None, delay=None, segment_type=None)[source]

Create a Waypoint as a geodesic offset from an anchor point.

Computes the destination via Vincenty direct-problem: from anchor along the great-circle initial bearing bearing for the given distance. Equivalent to Lait’s =FROM(loc, az, dist) position expression in the GSFC flight planner.

Parameters:

  • anchor (Waypoint | tuple[float, float]) – A Waypoint or (latitude, longitude) tuple to anchor against. Latitude and longitude must be in decimal degrees.

  • bearing (float) – Initial great-circle bearing from anchor, in degrees true (clockwise from north). Wrapped to [0, 360).

  • distance (Quantity) – Geodesic distance along that bearing, as a pint Quantity with length units — e.g. 200 * ureg.nautical_mile or 5 * ureg.km. Bare numbers are rejected: the rest of the HyPlan API reads them as meters while flight-planning shorthand reads them as nautical miles, so an explicit unit is required.

  • heading (float | None) – Heading of the new waypoint in degrees true. If None (default), copies bearing so the waypoint faces the direction it was offset toward — the ergonomic “fly toward the new point” default.

  • altitude_msl (Quantity | float | None) – Altitude MSL. Float interpreted as metres or a pint Quantity with length units; None leaves it unset.

  • name (str | None) – Optional name for the new waypoint.

  • speed (Quantity | float | None) – Optional speed override for the departing leg.

  • delay (Quantity | float | None) – Optional loiter time at the new waypoint.

  • segment_type (str | None) – Optional segment-type label.

Return type:

Waypoint

Returns:

A new Waypoint at the computed destination.

Examples

>>> from hyplan.units import ureg
>>> edw = Waypoint(latitude=34.92, longitude=-117.87,
...                heading=0, name="EDW")
>>> wp_a = Waypoint.relative_to(
...     edw, bearing=90, distance=200 * ureg.nautical_mile,
... )
>>> # wp_a is 200 nmi true east of EDW

>>> wp_b = Waypoint.relative_to(
...     (34.92, -117.87),
...     bearing=180,
...     distance=50 * ureg.kilometer,
...     heading=270,
...     name="WP_B",
... )

Helper functions

is_waypoint(obj)[source]

Check if an object is a Waypoint (duck-type safe for notebook reloads).

Return type:

TypeGuard[Waypoint]

Parameters:

obj (Any)