starplot 0.20.5__py3-none-any.whl

starplot/models/__init__.py

@@ -0,0 +1,21 @@
+# ruff: noqa: F401,F403
+
+from .constellation import Constellation, ConstellationBorder
+from .comet import Comet
+from .dso import DSO, DsoType
+from .star import Star
+from .planet import Planet
+from .moon import Moon
+from .sun import Sun
+from .optics import (
+    Optic,
+    Scope,
+    Reflector,
+    Refractor,
+    Binoculars,
+    Camera,
+)
+from .objects import ObjectList
+from .satellite import Satellite
+from .observer import Observer
+from .milky_way import MilkyWay

starplot/models/base.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass, fields
+from functools import cache
+from typing import Optional
+
+import pyarrow as pa
+from skyfield.api import position_of_radec, load_constellation_map
+
+from starplot.mixins import CreateMapMixin, CreateOpticMixin
+
+
+@cache
+def constellation_at():
+    return load_constellation_map()
+
+
+@dataclass(slots=True, kw_only=True)
+class SkyObject(
+    CreateMapMixin,
+    CreateOpticMixin,
+):
+    """
+    Base class for sky objects.
+
+    All sky object classes inherit from this base class.
+    """
+
+    ra: float
+    """Right Ascension, in degrees (0 to 360)"""
+
+    dec: float
+    """Declination, in degrees (-90 to 90)"""
+
+    constellation_id: Optional[str] = None
+    """Three-letter IAU id of the constellation that contains this object"""
+
+    healpix_index: int = None
+    """[HEALPix](https://en.wikipedia.org/wiki/HEALPix) pixel index of this object's RA/DEC"""
+
+    def constellation(self):
+        """Returns an instance of the [`Constellation`][starplot.models.Constellation] that contains this object, or `None` if no constellation is found."""
+        from starplot.models import Constellation
+
+        return Constellation.get(iau_id=self.constellation_id)
+
+    def populate_constellation_id(self):
+        """Populates the constellation_id field based on the location of this object"""
+        pos = position_of_radec(self.ra / 15, self.dec)
+        self.constellation_id = constellation_at()(pos).lower()
+
+    @classmethod
+    @cache
+    def _dir(cls):
+        return dir(cls)
+
+    @classmethod
+    @cache
+    def _fields(cls):
+        return [f.name for f in fields(cls)]
+
+    @classmethod
+    @cache
+    def _pyarrow_schema(cls):
+        """Returns explicit schema"""
+        return pa.schema(
+            [
+                pa.field("ra", pa.float64(), nullable=False),
+                pa.field("dec", pa.float64(), nullable=False),
+                pa.field("constellation_id", pa.string()),
+                pa.field("healpix_index", pa.int64()),
+            ]
+        )
+
+
+@dataclass(kw_only=True)
+class CatalogObject:
+    pk: int
+    """Primary key of object in catalog. Needs to be unique across all objects in the catalog."""

starplot/models/comet.py

@@ -0,0 +1,302 @@
+from datetime import datetime, timedelta
+from typing import Iterator
+from functools import cache
+from dataclasses import dataclass, fields
+
+from skyfield.data import mpc
+from skyfield.constants import GM_SUN_Pitjeva_2005_km3_s2 as GM_SUN
+from shapely import Point
+
+from starplot.data import load
+from starplot.models.base import SkyObject
+from starplot.models.observer import Observer
+
+
+@dataclass
+class SkyfieldComet:
+    designation: str
+    reference: str
+
+    perihelion_year: int
+    perihelion_month: int
+    perihelion_day: float
+    perihelion_distance_au: float
+    eccentricity: float
+    argument_of_perihelion_degrees: float
+    longitude_of_ascending_node_degrees: float
+    inclination_degrees: float
+
+    perturbed_epoch_year: int | None = None
+    perturbed_epoch_month: int | None = None
+    perturbed_epoch_day: int | None = None
+
+    number: int | None = None
+    designation_packed: str | None = None
+    orbit_type: str | None = None
+    magnitude_g: float | None = None
+    magnitude_k: float | None = None
+
+    # Skyfield columns
+    # ('number', (0, 4)),
+    # ('orbit_type', (4, 5)),
+    # ('designation_packed', (5, 12)),
+    # ('perihelion_year', (14, 18)),
+    # ('perihelion_month', (19, 21)),
+    # ('perihelion_day', (22, 29)),
+    # ('perihelion_distance_au', (30, 39)),
+    # ('eccentricity', (41, 49)),
+    # ('argument_of_perihelion_degrees', (51, 59)),
+    # ('longitude_of_ascending_node_degrees', (61, 69)),
+    # ('inclination_degrees', (71, 79)),
+    # ('perturbed_epoch_year', (81, 85)),
+    # ('perturbed_epoch_month', (85, 87)),
+    # ('perturbed_epoch_day', (87, 89)),
+    # ('magnitude_g', (91, 95)),
+    # ('magnitude_k', (96, 100)),
+    # ('designation', (102, 158)),
+    # ('reference', (159, 168)),
+
+    """
+    MPC JSON
+    {
+        "Comet_num": 483,
+        "Orbit_type": "P",
+        "Year_of_perihelion": 2027,
+        "Month_of_perihelion": 11,
+        "Day_of_perihelion": 11.7324,
+        "Perihelion_dist": 2.486784,
+        "e": 0.221733,
+        "Peri": 49.461,
+        "Node": 199.0602,
+        "i": 14.1756,
+        "Epoch_year": 2025,
+        "Epoch_month": 10,
+        "Epoch_day": 22,
+        "H": 17.0,
+        "G": 4.0,
+        "Designation_and_name": "483P-B/PANSTARRS",
+        "Ref": "MPC185666"
+    }
+    """
+
+    @classmethod
+    def from_mpc_json(cls, data: dict) -> "SkyfieldComet":
+        """Converts an MPC orbit JSON for a comet to a dataclass that Skyfield can work with"""
+
+        d = {k.lower(): v for k, v in data.items()}
+
+        return SkyfieldComet(
+            number=d.get("comet_num"),
+            orbit_type=d.get("orbit_type"),
+            designation_packed=d.get("provisional_packed_desig"),
+            perihelion_year=d.get("year_of_perihelion"),
+            perihelion_month=d.get("month_of_perihelion"),
+            perihelion_day=d.get("day_of_perihelion"),
+            perihelion_distance_au=d.get("perihelion_dist"),
+            eccentricity=d.get("e"),
+            argument_of_perihelion_degrees=d.get("peri"),
+            longitude_of_ascending_node_degrees=d.get("node"),
+            inclination_degrees=d.get("i"),
+            perturbed_epoch_year=d.get("epoch_year"),
+            perturbed_epoch_month=d.get("epoch_month"),
+            perturbed_epoch_day=d.get("epoch_day"),
+            magnitude_g=d.get("g"),
+            # magnitude_k=None, # no mapping?
+            designation=d.get("designation_and_name"),
+            reference=d.get("ref"),
+        )
+
+    @classmethod
+    def from_mpc_remote(cls, name: str, reload: bool) -> "SkyfieldComet":
+        """
+        Create a Skyfield comet by downloading the latest MPC comet data and finding the comet by name/designation
+
+        Args:
+            name: Name/designation of the comet
+            reload: If True, then the MPC data will be re-downloaded before finding the comet
+        """
+        comets = get_comets(reload)
+        row = comets.loc[name]
+        return SkyfieldComet(**row.to_dict())
+
+    def __getitem__(self, key):
+        """Allows accessing dataclass fields using dictionary-like syntax."""
+        if key in [f.name for f in fields(self)]:
+            return getattr(self, key)
+        else:
+            raise KeyError
+
+
+@dataclass(slots=True, kw_only=True)
+class Comet(SkyObject):
+    """
+    Comets can be created in three ways:
+
+    1. [`get`][starplot.Comet.get] (designation/name)
+    2. [`all`][starplot.Comet.all] (iterate through all comets available from MPC)
+    3. [`from_json`][starplot.Comet.from_json] (IAU MPC JSON)
+
+    """
+
+    name: str = None
+    """
+    Name of the comet (as designated by IAU Minor Planet Center)
+    """
+
+    observer: Observer = None
+    """Observer of this comet instance"""
+
+    distance: float | None = None
+    """Distance to comet, in Astronomical units (the Earth-Sun distance of 149,597,870,700 m)"""
+
+    ephemeris: str = None
+    """Ephemeris used when retrieving this instance"""
+
+    geometry: Point = None
+    """Shapely Point of the comet's position. Right ascension coordinates are in degrees (0...360)."""
+
+    data: SkyfieldComet = None
+
+    @classmethod
+    def from_json(
+        cls,
+        data: dict,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+    ) -> "Comet":
+        """
+        Get a comet for a specific date/time/location from an IAU MPC JSON.
+
+        Args:
+            data: Dictionary of the IAU MPC JSON
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating comet positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+        """
+        comet = SkyfieldComet.from_mpc_json(data)
+        observer = observer or Observer()
+
+        return get_comet_at_date_location(comet, observer, ephemeris)
+
+    @classmethod
+    def all(
+        cls,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+        reload: bool = False,
+    ) -> Iterator["Comet"]:
+        """
+        Iterator for getting all comets at a specific date/time and observing location.
+
+        Args:
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating comet positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+            reload: If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available.
+        """
+        comets = get_comets(reload=reload)
+        observer = observer or Observer()
+        for name in comets.index.values:
+            row = comets.loc[name]
+            comet = SkyfieldComet(**row.to_dict())
+            yield get_comet_at_date_location(
+                comet=comet,
+                observer=observer,
+                ephemeris=ephemeris,
+            )
+
+    @classmethod
+    def get(
+        cls,
+        name: str,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+        reload: bool = False,
+    ) -> "Comet":
+        """
+        Get a comet for a specific date/time.
+
+        Args:
+            name: Name of the comet you want to get (as designated by IAU Minor Planet Center)
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating comet positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+            reload: If True, then the comet data file will be re-downloaded. Otherwise, it'll use the existing file if available.
+        """
+        comet = SkyfieldComet.from_mpc_remote(name, reload)
+        observer = observer or Observer()
+        return get_comet_at_date_location(comet, observer, ephemeris)
+
+    def trajectory(
+        self, date_start: datetime, date_end: datetime, step: timedelta = None
+    ) -> Iterator["Comet"]:
+        """
+        Iterator for getting a trajectory of the comet.
+
+        Args:
+            date_start: Starting date/time for the trajectory (inclusive)
+            date_end: End date/time for the trajectory (exclusive)
+            step: Time-step for the trajectory. Defaults to 1-day
+
+        Returns:
+            Iterator that yields a Comet instance at each step in the date range
+        """
+        dt = date_start
+        step = step or timedelta(days=1)
+
+        while dt < date_end:
+            observer_kwargs = self.observer.model_dump()
+            observer_kwargs["dt"] = dt
+            new_observer = Observer(**observer_kwargs)
+            yield get_comet_at_date_location(
+                comet=self.data,
+                observer=new_observer,
+                ephemeris=self.ephemeris,
+            )
+            dt += step
+
+
+@cache
+def get_comets(reload=False):
+    """
+    Gets ALL comets currently tracked by IAU Minor Planet Center.
+
+    Args:
+        reload: If True, then redownload the comet data if it already exists
+
+    Returns:
+        DataFrame of all comets, indexed by name
+    """
+
+    with load.open(mpc.COMET_URL, reload=reload) as f:
+        comets = mpc.load_comets_dataframe(f)
+
+    # Keep only the most recent orbit for each comet, and index by designation for fast lookup.
+    comets = (
+        comets.sort_values("reference")
+        .groupby("designation", as_index=False)
+        .last()
+        .set_index("designation", drop=False)
+    )
+
+    return comets
+
+
+def get_comet_at_date_location(
+    comet: SkyfieldComet, observer: Observer, ephemeris: str
+) -> Comet:
+    """
+    Creates a Comet instance for date and (optional) observing location.
+    """
+    ts = load.timescale()
+    eph = load(ephemeris)
+    c = eph["sun"] + mpc.comet_orbit(comet, ts, GM_SUN)
+    ra, dec, distance = observer._astrometric(c, ephemeris=ephemeris)
+
+    return Comet(
+        name=comet.designation,
+        ra=ra.hours * 15,
+        dec=dec.degrees,
+        observer=observer,
+        distance=distance.au,
+        ephemeris=ephemeris,
+        geometry=Point(ra.hours * 15, dec.degrees),
+        data=comet,
+    )

starplot/models/constellation.py

@@ -0,0 +1,151 @@
+from typing import Iterator
+from dataclasses import dataclass
+
+from ibis import _
+from shapely import Polygon, MultiPolygon, LineString
+
+from starplot.models.base import SkyObject, CatalogObject
+from starplot.data.catalogs import Catalog, CONSTELLATIONS_IAU
+from starplot.data.constellations import load
+
+
+@dataclass(slots=True, kw_only=True)
+class Constellation(CatalogObject, SkyObject):
+    """
+    Constellation model.
+    """
+
+    boundary: Polygon | MultiPolygon
+    """
+    Shapely Polygon of the constellation's boundary. Right ascension coordinates are in degrees (0...360).
+    
+    If the constellation's boundary crosses the 0-meridian, then this will be a MultiPolygon split at the meridian.
+    """
+
+    star_hip_ids: list[int]
+    """List of HIP ids for stars that are part of the _lines_ for this constellation."""
+
+    star_hip_lines: list[list[int, int]]
+    """Nested list of star HIP ids that represent the lines of this constellation. Each pair of HIP ids represents a line between those stars."""
+
+    name: str = None
+    """Name of constellation"""
+
+    iau_id: str = None
+    """
+    International Astronomical Union (IAU) three-letter designation, all lowercase.
+    
+    **Important**: Starplot treats Serpens as two separate constellations to make them easier to work with programatically. 
+    Serpens Caput has the `iau_id` of `ser1` and Serpens Cauda is `ser2`
+    """
+
+    border: LineString = None
+    """
+    Shapely LineString of the constellation's border. Right ascension coordinates are in degrees (0...360).
+    
+    Coordinates in this geometry may extend past RA=360, if the border crosses the 0-meridian. This makes it ready to plot with the `line` function.
+    """
+
+    def __repr__(self) -> str:
+        return f"Constellation(iau_id={self.iau_id}, name={self.name}, ra={self.ra}, dec={self.dec})"
+
+    @classmethod
+    def all(cls, catalog: Catalog = CONSTELLATIONS_IAU) -> Iterator["Constellation"]:
+        """
+        Get all constellations from a catalog
+
+        Args:
+            catalog: Catalog you want to get constellation objects from
+
+        Returns:
+            Iterator of Constellation instances
+        """
+        df = load(catalog=catalog).to_pandas()
+
+        for c in df.itertuples():
+            yield from_tuple(c)
+
+    @classmethod
+    def get(
+        cls, catalog: Catalog = CONSTELLATIONS_IAU, sql: str = None, **kwargs
+    ) -> "Constellation":
+        """
+        Get a Constellation, by matching its attributes.
+
+        Example:
+
+            hercules = Constellation.get(name="Hercules")
+
+        Args:
+            catalog: The catalog of constellations to use
+            sql: SQL query for selecting constellation (table name is "_")
+            **kwargs: Attributes on the constellation you want to match
+
+        Raises: `ValueError` if more than one constellation is matched
+        """
+        filters = []
+
+        for k, v in kwargs.items():
+            filters.append(getattr(_, k) == v)
+
+        df = load(catalog=catalog, filters=filters, sql=sql).to_pandas()
+        results = [from_tuple(c) for c in df.itertuples()]
+
+        if len(results) == 1:
+            return results[0]
+
+        if len(results) > 1:
+            raise ValueError(
+                "More than one match. Use find() instead or narrow your search."
+            )
+
+        return None
+
+    @classmethod
+    def find(
+        cls,
+        catalog: Catalog = CONSTELLATIONS_IAU,
+        where: list = None,
+        sql: str = None,
+    ) -> list["Constellation"]:
+        """
+        Find Constellations
+
+        Args:
+            catalog: The catalog of constellations to use
+            where: A list of expressions that determine which constellations to find. See [Selecting Objects](/reference-selecting-objects/) for details.
+            sql: SQL query for selecting constellations (table name is "_")
+
+        Returns:
+            List of Constellations that match all `where` expressions
+
+        """
+        df = load(catalog=catalog, filters=where, sql=sql).to_pandas()
+
+        return [from_tuple(c) for c in df.itertuples()]
+
+    def constellation(self):
+        """Not applicable to Constellation model, raises `NotImplementedError`"""
+        raise NotImplementedError()
+
+    @classmethod
+    def get_label(cls, constellation):
+        """
+        Default function for determining the plotted label for a constellation
+
+        Returns the uppercase name of the constellation.
+
+        """
+        return constellation.name.upper().replace(" ", "\n")
+
+
+def from_tuple(c: tuple) -> Constellation:
+    kwargs = {f: getattr(c, f) for f in Constellation._fields() if hasattr(c, f)}
+    c = Constellation(**kwargs)
+    return c
+
+
+@dataclass(slots=True, kw_only=True)
+class ConstellationBorder(CatalogObject, SkyObject):
+    geometry: LineString
+    """Shapely LineString of the border. Right ascension coordinates are in degrees (0...360)."""