missiontools 0.1.0__tar.gz

missiontools-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Peter Kazakoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

missiontools-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: missiontools
+Version: 0.1.0
+Summary: Space mission analysis and design (SMAD) toolkit
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/neuroblaze/missiontools
+Project-URL: Documentation, https://missiontools.readthedocs.io/
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: skyfield
+Requires-Dist: pyshp
+Requires-Dist: shapely
+Requires-Dist: itur
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Provides-Extra: plot
+Requires-Dist: cartopy; extra == "plot"
+Dynamic: license-file
+
+# `missiontools`: Space Mission Analysis in Python
+
+`missiontools` is an MIT-licensed framework for space mission analysis tasks in Python. It is currently focused on Earth-orbiting missions, earth observation (EO) in particular.
+
+**If you are arriving here from a web search:** this package is under very active development and is probably not useful to you yet. APIs are subject to change without notice.
+
+**Check out the [examples folder](examples/) to see what you can do with `missiontools`**
+
+## Features
+
+`missiontools` currently supports:
+ - Analytical propagation using either Keplerian two-body or J2 with secular perturbations.
+ - Convenience functions for generating sun-synchronous, geostationary, and highly elliptical orbits.
+ - Access interval computation (spacecraft to ground station, spacecraft to spacecraft)
+ - Creation of areas of interest (AoIs) for coverage analysis: global, latitude/longitude bounding box, ESRI shapefile.
+ - Convenience functions for creation of AoIs by country or state/province (eg: `AoI.from_geography('Canada/British Columbia')`). Uses the [Natural Earth](https://www.naturalearthdata.com) 1:50m dataset.
+ - Computation of space-to-ground coverage including constraints on spacecraft elevation, solar zenith angle (SZA), and field-of-view.
+ - Selectable spacecraft attitude laws: fixed (choice of frame: LVLH, ECI, ECEF), targeted
+ - Solar panel definition from panel normals and areas
+ - Solar generation and orbit average power
+ - Yaw steering for maximum solar generation
+ - Thermal analysis: faces/normals connected to lumped element thermal model
+ - Antenna modeling (isotropic, radially symmetric), including antenna pointing modes
+ - Dynamic link budget computation including ITU-R P.618 weather effects (using [ITU-RPy](https://itu-rpy.readthedocs.io/en/latest/)).
+ 
+ Possible future features (open an issue if you'd like to see one of these implemented):
+ - CAD import for solar & thermal
+ - Self-shadowing for solar/thermal imported from CAD
+ - Radiative thermal coupling between surface elements imported from CAD
+ - Variable-rate communications
+ - Radiation environment definition
+
+## Dependencies
+ - Python 3.13 or later
+ - numpy
+ - scipy
+ - matplotlib
+ - skyfield
+ - pyshp
+ - shapely
+ - itur
+
+## Validation
+
+This project is in early days and is not yet well validated. Do not depend on the outputs for any critical design decisions. If an output looks off, it probably is - please open an issue!
+
+## Vibe Coding Disclaimer
+
+This project is my first foray into agentic development. I make the architecture decisions myself and use Claude Code to implement them - generating functions, classes, and tests from my specifications. I review all output and redirect when needed, but I do not generally write the implementation code directly.
+
+## Acknowledgements
+ - [Natural Earth](https://www.naturalearthdata.com) for the country/state/province shapefiles
+ - Claude Sonnet 4.6 & Opus 4.6 for doing the implementation gruntwork

missiontools-0.1.0/README.md

@@ -0,0 +1,53 @@
+# `missiontools`: Space Mission Analysis in Python
+
+`missiontools` is an MIT-licensed framework for space mission analysis tasks in Python. It is currently focused on Earth-orbiting missions, earth observation (EO) in particular.
+
+**If you are arriving here from a web search:** this package is under very active development and is probably not useful to you yet. APIs are subject to change without notice.
+
+**Check out the [examples folder](examples/) to see what you can do with `missiontools`**
+
+## Features
+
+`missiontools` currently supports:
+ - Analytical propagation using either Keplerian two-body or J2 with secular perturbations.
+ - Convenience functions for generating sun-synchronous, geostationary, and highly elliptical orbits.
+ - Access interval computation (spacecraft to ground station, spacecraft to spacecraft)
+ - Creation of areas of interest (AoIs) for coverage analysis: global, latitude/longitude bounding box, ESRI shapefile.
+ - Convenience functions for creation of AoIs by country or state/province (eg: `AoI.from_geography('Canada/British Columbia')`). Uses the [Natural Earth](https://www.naturalearthdata.com) 1:50m dataset.
+ - Computation of space-to-ground coverage including constraints on spacecraft elevation, solar zenith angle (SZA), and field-of-view.
+ - Selectable spacecraft attitude laws: fixed (choice of frame: LVLH, ECI, ECEF), targeted
+ - Solar panel definition from panel normals and areas
+ - Solar generation and orbit average power
+ - Yaw steering for maximum solar generation
+ - Thermal analysis: faces/normals connected to lumped element thermal model
+ - Antenna modeling (isotropic, radially symmetric), including antenna pointing modes
+ - Dynamic link budget computation including ITU-R P.618 weather effects (using [ITU-RPy](https://itu-rpy.readthedocs.io/en/latest/)).
+ 
+ Possible future features (open an issue if you'd like to see one of these implemented):
+ - CAD import for solar & thermal
+ - Self-shadowing for solar/thermal imported from CAD
+ - Radiative thermal coupling between surface elements imported from CAD
+ - Variable-rate communications
+ - Radiation environment definition
+
+## Dependencies
+ - Python 3.13 or later
+ - numpy
+ - scipy
+ - matplotlib
+ - skyfield
+ - pyshp
+ - shapely
+ - itur
+
+## Validation
+
+This project is in early days and is not yet well validated. Do not depend on the outputs for any critical design decisions. If an output looks off, it probably is - please open an issue!
+
+## Vibe Coding Disclaimer
+
+This project is my first foray into agentic development. I make the architecture decisions myself and use Claude Code to implement them - generating functions, classes, and tests from my specifications. I review all output and redirect when needed, but I do not generally write the implementation code directly.
+
+## Acknowledgements
+ - [Natural Earth](https://www.naturalearthdata.com) for the country/state/province shapefiles
+ - Claude Sonnet 4.6 & Opus 4.6 for doing the implementation gruntwork

missiontools-0.1.0/missiontools/__init__.py

@@ -0,0 +1,122 @@
+"""
+missiontools
+============
+Space mission analysis and design (SMAD) toolkit.
+
+missiontools provides a high-level Python interface for spacecraft mission
+analysis, covering orbital mechanics, coverage and access analysis, attitude
+determination and control, and solar power modelling.
+
+Quick start
+-----------
+Propagate a sun-synchronous LEO orbit for one day::
+
+    import numpy as np
+    from missiontools import Spacecraft
+
+    sc = Spacecraft.sunsync(altitude_km=550, node_solar_time='10:30')
+    state = sc.propagate(
+        np.datetime64('2025-01-01', 'us'),
+        np.datetime64('2025-01-02', 'us'),
+        np.timedelta64(60, 's'),
+    )
+    # state['r'] — (N, 3) ECI position array (m)
+    # state['v'] — (N, 3) ECI velocity array (m/s)
+
+Compute ground coverage::
+
+    from missiontools import AoI, Coverage, Sensor
+
+    sensor = Sensor(30.0, body_vector=[0, 0, 1])
+    sc.add_sensor(sensor)
+
+    aoi    = AoI.from_geography('Australia')
+    cov    = Coverage(aoi, [sensor])
+    result = cov.coverage_fraction(
+        np.datetime64('2025-01-01', 'us'),
+        np.datetime64('2025-01-02', 'us'),
+    )
+    print(f"1-day coverage: {result['final_cumulative']:.1%}")
+
+Classes
+-------
+:class:`Spacecraft`
+    Defines a satellite orbit via Keplerian elements.  Factory methods
+    :meth:`~Spacecraft.sunsync`, :meth:`~Spacecraft.geostationary`, and
+    :meth:`~Spacecraft.heo` cover the most common orbit types.
+:class:`Sensor`
+    An instrument with a conical field of view, attached to a spacecraft
+    via :meth:`~Spacecraft.add_sensor`.
+:class:`AttitudeLaw`
+    Spacecraft or sensor pointing law.  Supports nadir, fixed-frame, and
+    target-tracking modes with optional yaw steering.
+:class:`GroundStation`
+    A ground station defined in WGS84 geodetic coordinates, with an
+    :meth:`~GroundStation.access` method for contact scheduling.
+:class:`AoI`
+    Area of interest defined by a sampled point cloud.  Factory methods
+    :meth:`~AoI.from_region`, :meth:`~AoI.from_shapefile`, and
+    :meth:`~AoI.from_geography` cover rectangular regions, ESRI shapefiles,
+    and Natural Earth geographies respectively.
+:class:`Coverage`
+    Coverage and revisit analysis for one or more sensors over an AoI.
+    Supports single-satellite and constellation configurations.
+:class:`AbstractSolarConfig`
+    Abstract base class for solar power models.
+:class:`NormalVectorSolarConfig`
+    Concrete solar config defined by panel normal vectors and areas.
+:class:`ThermalCircuit`
+    Lumped-parameter thermal network for transient and steady-state analysis.
+:class:`NormalVectorThermalConfig`
+    Surface thermal config defined by face normal vectors, areas,
+    emissivities, and absorptivities.
+:class:`ThermalResult`
+    Container for thermal simulation results (node temperature histories).
+:class:`AbstractThermalConfig`
+    Base class for surface thermal configurations.
+
+Conventions
+-----------
+- All physical quantities use SI base units (m, kg, s, A, K, ...) unless
+  explicitly stated otherwise in a function's docstring.
+- All angles are in radians unless explicitly stated otherwise.
+
+Submodules
+----------
+:mod:`~missiontools.orbit`
+    Orbital mechanics, propagation, frame transformations, and access analysis.
+:mod:`~missiontools.attitude`
+    Attitude law representations.
+:mod:`~missiontools.coverage`
+    Coverage and access analysis, geographic area sampling.
+:mod:`~missiontools.power`
+    Solar power generation modelling.
+:mod:`~missiontools.comm`
+    Antenna gain and link budget analysis.
+:mod:`~missiontools.thermal`
+    Thermal analysis: lumped-parameter networks and surface thermal models.
+:mod:`~missiontools.radiation`
+    Radiation environment *(planned)*.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = [
+    'Spacecraft', 'Sensor', 'AttitudeLaw', 'GroundStation', 'AoI', 'Coverage',
+    'AbstractSolarConfig', 'NormalVectorSolarConfig',
+    'ThermalCircuit', 'ThermalResult', 'AbstractThermalConfig', 'NormalVectorThermalConfig',
+    'IsotropicAntenna', 'SymmetricAntenna', 'Link',
+    'clear_cache', 'set_cache_limit', 'cache_info',
+]
+
+from .spacecraft import Spacecraft
+from .attitude import AttitudeLaw
+from .ground_station import GroundStation
+from .aoi import AoI
+from .sensor import Sensor
+from .coverage_analysis import Coverage
+from .power import AbstractSolarConfig, NormalVectorSolarConfig
+from .thermal import (ThermalCircuit, ThermalResult,
+                      AbstractThermalConfig, NormalVectorThermalConfig)
+from .comm import IsotropicAntenna, SymmetricAntenna, Link
+from .cache import clear_cache, set_cache_limit, cache_info

missiontools-0.1.0/missiontools/aoi.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+
+def _geom_crosses_am(geom) -> bool:
+    """Return True if *geom*'s bounding box extends outside [-180, 180] longitude."""
+    if geom.is_empty:
+        return False
+    b = geom.bounds   # (minx, miny, maxx, maxy)
+    return b[2] > 180.0 or b[0] < -180.0
+
+
+class AoI:
+    """Area of interest defined by a sampled point cloud.
+
+    All angles are in degrees at the user-facing interface; internally stored
+    as radians.  The ``lat_rad`` / ``lon_rad`` properties expose the radians
+    representation for direct use with coverage analysis functions.
+
+    AoIs created via :meth:`from_region`, :meth:`from_shapefile`,
+    :meth:`from_geography`, or a set operation are **geometry-backed** — they
+    store a Shapely geometry and generate their sample points **lazily** on
+    first access.  This means composing complex AoIs with set operations
+    (``|``, ``&``, ``-``, ``^``) incurs no sampling cost until points are
+    actually needed.
+
+    Parameters
+    ----------
+    lat_deg : array-like
+        Sample latitudes (deg), shape ``(M,)``.
+    lon_deg : array-like
+        Sample longitudes (deg), shape ``(M,)``.
+
+    Notes
+    -----
+    Directly constructed AoIs (``AoI(lat, lon)``) have no associated geometry
+    and cannot participate in set operations.
+
+    **Antimeridian caveat**: set operations between a geometry from a Natural
+    Earth shapefile that uses unwrapped longitudes (> 180°, e.g. Russia) and
+    a :meth:`from_region` box in [-180, 180] will not behave correctly because
+    Shapely treats coordinates as Cartesian.  For most geographies this is not
+    an issue.
+
+    Examples
+    --------
+    Direct construction from arrays::
+
+        import numpy as np
+        from missiontools import AoI
+
+        lat = np.linspace(-10, 10, 50)
+        lon = np.linspace(30, 60, 50)
+        aoi = AoI(lat, lon)
+
+    From a rectangular lat/lon band (lazy — no points generated yet)::
+
+        aoi = AoI.from_region(lat_min_deg=-10, lat_max_deg=10,
+                               lon_min_deg=30,  lon_max_deg=60)
+
+    From a Natural Earth geography::
+
+        aoi = AoI.from_geography('Australia')
+
+    Compound AoI via set operations::
+
+        conus = AoI.from_geography("US") - AoI.from_geography("US-AK") \\
+                                         - AoI.from_geography("US-HI")
+
+        can_arctic = AoI.from_geography("Canada") & AoI.from_region(lat_min_deg=66)
+    """
+
+    def __init__(self, lat_deg: npt.ArrayLike, lon_deg: npt.ArrayLike) -> None:
+        self._lat = np.radians(np.asarray(lat_deg, dtype=np.float64))
+        self._lon = np.radians(np.asarray(lon_deg, dtype=np.float64))
+        self._geometry = None
+        self._shapefile_path = None
+        self._point_density_m2 = None
+        self._crosses_am = False
+
+    # ------------------------------------------------------------------
+    # Private lazy-construction classmethod
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _from_geometry(
+            cls,
+            geom,
+            crosses_am: bool,
+            density_m2: float,
+            shapefile_path: str | None = None,
+    ) -> 'AoI':
+        """Construct a lazy AoI backed by a Shapely geometry.
+
+        Points are not sampled until first access via a point-returning property.
+        """
+        obj = object.__new__(cls)
+        obj._lat = None          # lazy: computed on demand
+        obj._lon = None
+        obj._geometry = geom
+        obj._shapefile_path = shapefile_path
+        obj._point_density_m2 = density_m2
+        obj._crosses_am = crosses_am
+        return obj
+
+    # ------------------------------------------------------------------
+    # Lazy evaluation
+    # ------------------------------------------------------------------
+
+    def _ensure_points(self) -> None:
+        """Compute sample points from geometry if they have not been generated yet."""
+        if self._lat is not None:
+            return
+        from .coverage.coverage import sample_from_geometry
+        if self._geometry.is_empty:
+            self._lat = np.empty(0, dtype=np.float64)
+            self._lon = np.empty(0, dtype=np.float64)
+        else:
+            self._lat, self._lon = sample_from_geometry(
+                self._geometry, self._crosses_am, self._point_density_m2
+            )
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def lat(self) -> npt.NDArray[np.float64]:
+        """Sample latitudes (deg), shape ``(M,)``."""
+        self._ensure_points()
+        return np.degrees(self._lat)
+
+    @property
+    def lon(self) -> npt.NDArray[np.float64]:
+        """Sample longitudes (deg), shape ``(M,)``."""
+        self._ensure_points()
+        return np.degrees(self._lon)
+
+    @property
+    def lat_rad(self) -> npt.NDArray[np.float64]:
+        """Sample latitudes (rad), shape ``(M,)`` — for coverage functions."""
+        self._ensure_points()
+        return self._lat
+
+    @property
+    def lon_rad(self) -> npt.NDArray[np.float64]:
+        """Sample longitudes (rad), shape ``(M,)`` — for coverage functions."""
+        self._ensure_points()
+        return self._lon
+
+    @property
+    def geometry(self):
+        """Shapely geometry describing the AoI, or ``None`` if unavailable."""
+        return self._geometry
+
+    @property
+    def shapefile_path(self) -> str | None:
+        """Path to the source shapefile, or ``None`` if not constructed from one."""
+        return self._shapefile_path
+
+    def __len__(self) -> int:
+        self._ensure_points()
+        return len(self._lat)
+
+    def __repr__(self) -> str:
+        pts = (f'{len(self._lat)} points'
+               if self._lat is not None else 'not yet sampled')
+        if self._shapefile_path:
+            return f'AoI({pts}, shapefile={self._shapefile_path!r})'
+        if self._geometry is not None:
+            return f'AoI({pts}, {type(self._geometry).__name__})'
+        return f'AoI({pts})'
+
+    # ------------------------------------------------------------------
+    # Set operations
+    # ------------------------------------------------------------------
+
+    def _require_geometry(self, op: str) -> None:
+        if self._geometry is None:
+            raise TypeError(
+                f"Cannot use '{op}' on an AoI without associated geometry. "
+                "Use from_region(), from_shapefile(), from_geography(), "
+                "or a set operation to create a geometry-backed AoI."
+            )
+
+    def __or__(self, other: 'AoI') -> 'AoI':
+        """Union — all area covered by either AoI."""
+        self._require_geometry('|')
+        other._require_geometry('|')
+        geom = self._geometry.union(other._geometry)
+        return AoI._from_geometry(geom, _geom_crosses_am(geom), self._point_density_m2)
+
+    def __and__(self, other: 'AoI') -> 'AoI':
+        """Intersection — area common to both AoIs."""
+        self._require_geometry('&')
+        other._require_geometry('&')
+        geom = self._geometry.intersection(other._geometry)
+        return AoI._from_geometry(geom, _geom_crosses_am(geom), self._point_density_m2)
+
+    def __sub__(self, other: 'AoI') -> 'AoI':
+        """Difference — area in this AoI that is not in *other*."""
+        self._require_geometry('-')
+        other._require_geometry('-')
+        geom = self._geometry.difference(other._geometry)
+        return AoI._from_geometry(geom, _geom_crosses_am(geom), self._point_density_m2)
+
+    def __xor__(self, other: 'AoI') -> 'AoI':
+        """Symmetric difference — area in either AoI but not both."""
+        self._require_geometry('^')
+        other._require_geometry('^')
+        geom = self._geometry.symmetric_difference(other._geometry)
+        return AoI._from_geometry(geom, _geom_crosses_am(geom), self._point_density_m2)
+
+    # ------------------------------------------------------------------
+    # Factory classmethods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _from_radians(cls, lat_rad: npt.NDArray, lon_rad: npt.NDArray) -> 'AoI':
+        """Construct directly from radian arrays, skipping the deg→rad conversion."""
+        obj = object.__new__(cls)
+        obj._lat = np.asarray(lat_rad, dtype=np.float64)
+        obj._lon = np.asarray(lon_rad, dtype=np.float64)
+        obj._geometry = None
+        obj._shapefile_path = None
+        obj._point_density_m2 = None
+        obj._crosses_am = False
+        return obj
+
+    @classmethod
+    def from_region(
+            cls,
+            lat_min_deg: float | None = None,
+            lat_max_deg: float | None = None,
+            lon_min_deg: float | None = None,
+            lon_max_deg: float | None = None,
+            *,
+            point_density: float = 1e5,
+    ) -> 'AoI':
+        """Sample an AoI from a rectangular lat/lon region.
+
+        Points are generated lazily on first access.
+
+        Parameters
+        ----------
+        lat_min_deg : float | None, optional
+            Southern boundary (deg).  ``None`` extends to the South Pole.
+        lat_max_deg : float | None, optional
+            Northern boundary (deg).  ``None`` extends to the North Pole.
+        lon_min_deg : float | None, optional
+            Western boundary (deg).  Must be paired with ``lon_max_deg``; ``None``
+            (together with ``lon_max_deg=None``) includes all longitudes.
+        lon_max_deg : float | None, optional
+            Eastern boundary (deg).  May be less than ``lon_min_deg`` for
+            anti-meridian-crossing regions.
+        point_density : float, optional
+            Approximate area per sample point (km²).  Defaults to 1×10⁵ km²
+            (~100 000 km² per point).
+
+        Returns
+        -------
+        AoI
+            Geometry-backed, lazily sampled.
+        """
+        from shapely.geometry import box
+        from shapely.ops import unary_union
+
+        density_m2 = point_density * 1e6
+
+        lat_min = -90.0 if lat_min_deg is None else float(lat_min_deg)
+        lat_max =  90.0 if lat_max_deg is None else float(lat_max_deg)
+
+        if lon_min_deg is None and lon_max_deg is None:
+            geom = box(-180.0, lat_min, 180.0, lat_max)
+            crosses_am = False
+        elif lon_min_deg is not None and lon_max_deg is not None:
+            lon_min = float(lon_min_deg)
+            lon_max = float(lon_max_deg)
+            if lon_min <= lon_max:
+                geom = box(lon_min, lat_min, lon_max, lat_max)
+                crosses_am = False
+            else:
+                # antimeridian-crossing: two boxes in normal [-180, 180] coordinates
+                geom = unary_union([
+                    box(lon_min, lat_min, 180.0, lat_max),
+                    box(-180.0, lat_min, lon_max, lat_max),
+                ])
+                crosses_am = False
+        else:
+            raise ValueError(
+                "lon_min_deg and lon_max_deg must both be None or both be specified."
+            )
+
+        return cls._from_geometry(geom, crosses_am, density_m2)
+
+    @classmethod
+    def from_shapefile(
+            cls,
+            path: str,
+            *,
+            feature_index: int | None = None,
+            point_density: float = 1e5,
+    ) -> 'AoI':
+        """Sample an AoI from an ESRI Shapefile polygon.
+
+        Stores the Shapely geometry; points are generated lazily on first access.
+
+        Parameters
+        ----------
+        path : str
+            Path to the ``.shp`` file.
+        feature_index : int | None, optional
+            Index of the feature to sample.  ``None`` (default) unions all
+            features.
+        point_density : float, optional
+            Approximate area per sample point (km²).  Defaults to 1×10⁵ km².
+
+        Returns
+        -------
+        AoI
+            With :attr:`geometry` and :attr:`shapefile_path` populated.
+        """
+        from .coverage import load_shapefile_geometry
+
+        geom, crosses_am = load_shapefile_geometry(path, feature_index)
+        return cls._from_geometry(geom, crosses_am, point_density * 1e6,
+                                   shapefile_path=str(path))
+
+    @classmethod
+    def from_geography(
+            cls,
+            geography: str,
+            *,
+            point_density: float = 1e5,
+    ) -> 'AoI':
+        """Sample an AoI from a Natural Earth geography by name or code.
+
+        Stores the Shapely geometry; points are generated lazily on first access.
+
+        Parameters
+        ----------
+        geography : str
+            One of:
+
+            - Country name: ``'Canada'`` (case-insensitive)
+            - ``'Country/Subdivision'``: ``'Canada/Quebec'``
+            - ISO 3166-1 alpha-2: ``'CA'``
+            - ISO 3166-1 alpha-3: ``'CAN'``
+            - ISO 3166-2: ``'CA-QC'``
+        point_density : float, optional
+            Approximate area per sample point (km²).  Defaults to 1×10⁵ km².
+
+        Returns
+        -------
+        AoI
+            With :attr:`geometry` populated.
+        """
+        from .coverage import geography_geometry
+
+        geom, crosses_am = geography_geometry(geography)
+        return cls._from_geometry(geom, crosses_am, point_density * 1e6)

missiontools-0.1.0/missiontools/attitude/__init__.py

@@ -0,0 +1,36 @@
+"""
+missiontools.attitude
+=====================
+Spacecraft and sensor pointing laws.
+
+The primary class is :class:`AttitudeLaw`, which stores a full 3-DOF body
+orientation as a unit quaternion ``[w, x, y, z]`` and supports several
+pointing modes:
+
+- **Nadir** — body-z toward the Earth centre (default for all
+  :class:`~missiontools.Spacecraft` instances).
+- **Fixed** — constant body orientation in a chosen reference frame
+  (LVLH, ECI, or ECEF).  The boresight direction and an optional roll
+  angle are specified at construction.
+- **Track** — boresight pointing toward a target
+  :class:`~missiontools.Spacecraft` at every timestep.
+
+All pointing methods (:meth:`~AttitudeLaw.pointing_eci`,
+:meth:`~AttitudeLaw.pointing_lvlh`, :meth:`~AttitudeLaw.pointing_ecef`)
+return the **body-z** unit vector expressed in the requested frame.
+
+Optional yaw steering can be enabled via
+:meth:`~AttitudeLaw.yaw_steering` to maximise solar power generation by
+rotating the spacecraft about the boresight axis at each timestep.
+
+Planned functionality
+---------------------
+- Environmental disturbance torques
+- Actuator sizing (reaction wheels, magnetorquers, thrusters)
+- Pointing budget and error analysis
+- Sensor modelling (star tracker, sun sensor, magnetometer)
+"""
+
+from .attitude_law import AttitudeLaw
+
+__all__ = ['AttitudeLaw']