starplot 0.20.5__py3-none-any.whl

starplot/models/dso.py

@@ -0,0 +1,317 @@
+from dataclasses import dataclass
+from typing import Optional, Iterator
+from enum import Enum
+
+from ibis import _
+import pyarrow as pa
+from shapely import Polygon, MultiPolygon
+
+from starplot.data.utils import to_pandas
+from starplot.data.catalogs import Catalog, OPEN_NGC
+from starplot.data.dsos import load
+from starplot.models.base import SkyObject, CatalogObject
+
+
+class DsoType(str, Enum):
+    """
+    Type of deep sky object (DSO), as designated in OpenNGC
+    """
+
+    STAR = "*"
+    """Star"""
+
+    DOUBLE_STAR = "**"
+    """Double star or multiple star system"""
+
+    ASSOCIATION_OF_STARS = "*Ass"
+    """Association of stars"""
+
+    OPEN_CLUSTER = "OCl"
+    """Open cluster of stars"""
+
+    GLOBULAR_CLUSTER = "GCl"
+    """Globular cluster of stars"""
+
+    GALAXY = "G"
+    """Galaxy"""
+
+    GALAXY_PAIR = "GPair"
+    """Group of two galaxies"""
+
+    GALAXY_TRIPLET = "GTrpl"
+    """Group of three galaxies"""
+
+    GROUP_OF_GALAXIES = "GGroup"
+    """Group of more than three galaxies"""
+
+    NEBULA = "Neb"
+    """Nebula"""
+
+    PLANETARY_NEBULA = "PN"
+    """Planetary nebula"""
+
+    EMISSION_NEBULA = "EmN"
+    """Emission Nebula"""
+
+    STAR_CLUSTER_NEBULA = "Cl+N"
+    """Star cluster with nebulosity"""
+
+    REFLECTION_NEBULA = "RfN"
+    """Reflection nebula"""
+
+    DARK_NEBULA = "DrkN"
+    """Dark nebula"""
+
+    HII_IONIZED_REGION = "HII"
+    """Hydrogen ionized region"""
+
+    SUPERNOVA_REMNANT = "SNR"
+    """Supernova remnant"""
+
+    NOVA_STAR = "Nova"
+    """Nova star"""
+
+    NONEXISTENT = "NonEx"
+    """Non-existant object"""
+
+    UNKNOWN = "Other"
+    """Unknown type of object"""
+
+    DUPLICATE_RECORD = "Dup"
+    """Duplicate record of another object"""
+
+
+@dataclass(slots=True, kw_only=True)
+class DSO(CatalogObject, SkyObject):
+    """
+    Deep Sky Object (DSO) model. An instance of this model is passed to any [callables](/reference-callables) you define when plotting DSOs.
+    So, you can use any attributes of this model in your callables. Note that some may be null.
+    """
+
+    geometry: Polygon | MultiPolygon
+    """Shapely Polygon of the DSO's extent. Right ascension coordinates are in degrees (0...360)."""
+
+    name: str = None
+    """Name of the DSO (as specified in OpenNGC)"""
+
+    type: DsoType = DsoType.UNKNOWN
+    """Type of DSO"""
+
+    common_names: list[str] = None
+    """
+    List of common names for the DSO (e.g. 'Andromeda Galaxy' for M31)
+    
+    Note: this field is parsed into a list of strings _after_ querying DSOs, so if you want to query on this field, you should treat it as a comma-separated list.
+    """
+
+    magnitude: Optional[float] = None
+    """Magnitude (if available)"""
+
+    maj_ax: Optional[float] = None
+    """Major axis of the DSO, in arcmin (if available)"""
+
+    min_ax: Optional[float] = None
+    """Minor axis of the DSO, in arcmin (if available)"""
+
+    angle: Optional[float] = None
+    """Angle of the DSO, in degrees (if available)"""
+
+    size: Optional[float] = None
+    """Size of the DSO calculated as the area of the minimum bounding rectangle of the DSO, in degrees squared (if available)"""
+
+    m: Optional[str] = None
+    """
+    Messier number. *Note that this field is a string, to be consistent with the other identifier fields (`ngc` and `ic`).*
+    """
+
+    ngc: Optional[str] = None
+    """
+    New General Catalogue (NGC) identifier. *Note that this field is a string, to support objects like '3537 NED01'.*
+    """
+
+    ic: Optional[str] = None
+    """
+    Index Catalogue (IC) identifier. *Note that this field is a string, to support objects like '4974 NED01'.*
+    """
+
+    @classmethod
+    def _pyarrow_schema(cls):
+        base_schema = super(DSO, cls)._pyarrow_schema()
+        dso_fields = [
+            pa.field("pk", pa.int64(), nullable=False),
+            pa.field("geometry", pa.binary(), nullable=False),
+            pa.field("name", pa.string()),
+            pa.field("type", pa.string()),
+            pa.field("common_names", pa.string()),
+            pa.field("magnitude", pa.float64()),
+            pa.field("maj_ax", pa.float64()),
+            pa.field("min_ax", pa.float64()),
+            pa.field("angle", pa.float64()),
+            pa.field("size", pa.float64()),
+            pa.field("m", pa.string()),
+            pa.field("ngc", pa.string()),
+            pa.field("ic", pa.string()),
+        ]
+        return pa.schema(list(base_schema) + dso_fields)
+
+    def __repr__(self) -> str:
+        return f"DSO(name={self.name}, magnitude={self.magnitude})"
+
+    @classmethod
+    def all(cls, catalog: Catalog = OPEN_NGC) -> Iterator["DSO"]:
+        """
+        Get all DSOs from a catalog
+
+        Args:
+            catalog: Catalog you want to get DSO objects from
+
+        Returns:
+            Iterator of DSO instances
+        """
+        df = to_pandas(load(catalog=catalog))
+
+        for d in df.itertuples():
+            yield from_tuple(d)
+
+    @classmethod
+    def get(cls, catalog: Catalog = OPEN_NGC, sql: str = None, **kwargs) -> "DSO":
+        """
+        Get a DSO, by matching its attributes.
+
+        Example:
+
+            d = DSO.get(m=13)
+
+        Args:
+            catalog: Catalog you want to search
+            sql: SQL query for selecting DSO (table name is "_")
+            **kwargs: Attributes on the DSO you want to match
+
+        Raises: `ValueError` if more than one DSO is matched
+        """
+        filters = []
+
+        for k, v in kwargs.items():
+            filters.append(getattr(_, k) == v)
+
+        df = to_pandas(load(catalog=catalog, filters=filters, sql=sql))
+
+        results = [from_tuple(d) for d 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 = OPEN_NGC, where: list = None, sql: str = None
+    ) -> list["DSO"]:
+        """
+        Find DSOs
+
+        Args:
+            catalog: Catalog you want to search
+            where: A list of expressions that determine which DSOs to find. See [Selecting Objects](/reference-selecting-objects/) for details.
+            sql: SQL query for selecting DSOs (table name is "_")
+
+        Returns:
+            List of DSOs that match all `where` expressions
+
+        """
+        df = to_pandas(load(catalog=catalog, filters=where, sql=sql))
+        return [from_tuple(d) for d in df.itertuples()]
+
+    @classmethod
+    def get_label(cls, dso) -> str:
+        """
+        Default function for determining the plotted label for a DSO.
+
+        Returns:
+
+        1. `"M13"` if DSO is a Messier object
+        2. `"6456"` if DSO is an NGC object
+        3. `"IC1920"` if DSO is an IC object
+        4. Empty string otherwise
+
+        """
+        if dso.m:
+            return f"M{dso.m}"
+
+        if dso.ngc:
+            return f"{dso.ngc}"
+
+        if dso.ic:
+            return f"IC{dso.ic}"
+
+        return ""
+
+
+def from_tuple(d: tuple) -> DSO:
+    kwargs = {f: getattr(d, f) for f in DSO._fields() if hasattr(d, f)}
+    if "common_names" in kwargs and kwargs["common_names"] is not None:
+        kwargs["common_names"] = kwargs["common_names"].split(",")
+
+    return DSO(**kwargs)
+
+
+ONGC_TYPE = {
+    # Star Clusters ----------
+    DsoType.OPEN_CLUSTER: "OCl",
+    DsoType.GLOBULAR_CLUSTER: "GCl",
+    # Galaxies ----------
+    DsoType.GALAXY: "G",
+    DsoType.GALAXY_PAIR: "GPair",
+    DsoType.GALAXY_TRIPLET: "GTrpl",
+    DsoType.GROUP_OF_GALAXIES: "GGroup",
+    # Nebulas ----------
+    DsoType.NEBULA: "Neb",
+    DsoType.PLANETARY_NEBULA: "PN",
+    DsoType.EMISSION_NEBULA: "EmN",
+    DsoType.STAR_CLUSTER_NEBULA: "Cl+N",
+    DsoType.REFLECTION_NEBULA: "RfN",
+    # Stars ----------
+    DsoType.STAR: "*",
+    DsoType.DOUBLE_STAR: "**",
+    DsoType.ASSOCIATION_OF_STARS: "*Ass",
+    # Others
+    DsoType.HII_IONIZED_REGION: "HII",
+    DsoType.DARK_NEBULA: "DrkN",
+    DsoType.SUPERNOVA_REMNANT: "SNR",
+    DsoType.NOVA_STAR: "Nova",
+    DsoType.NONEXISTENT: "NonEx",
+    DsoType.UNKNOWN: "Other",
+    DsoType.DUPLICATE_RECORD: "Dup",
+}
+
+ONGC_TYPE_MAP = {v: k for k, v in ONGC_TYPE.items()}
+
+DSO_LEGEND_LABELS = {
+    # Galaxies ----------
+    DsoType.GALAXY: "Galaxy",
+    DsoType.GALAXY_PAIR: "Galaxy",
+    DsoType.GALAXY_TRIPLET: "Galaxy",
+    DsoType.GROUP_OF_GALAXIES: "Galaxy",
+    # Nebulas ----------
+    DsoType.NEBULA: "Nebula",
+    DsoType.PLANETARY_NEBULA: "Planetary Nebula",
+    DsoType.EMISSION_NEBULA: "Nebula",
+    DsoType.STAR_CLUSTER_NEBULA: "Nebula",
+    DsoType.REFLECTION_NEBULA: "Nebula",
+    DsoType.HII_IONIZED_REGION: "Nebula",
+    # Star Clusters ----------
+    DsoType.OPEN_CLUSTER: "Open Cluster",
+    DsoType.GLOBULAR_CLUSTER: "Globular Cluster",
+    # Stars ----------
+    DsoType.DOUBLE_STAR: "Double Star",
+    DsoType.ASSOCIATION_OF_STARS: "Association of stars",
+    DsoType.NOVA_STAR: "Nova Star",
+    # Others
+    DsoType.DARK_NEBULA: "Dark Nebula",
+    DsoType.SUPERNOVA_REMNANT: "Supernova Remnant",
+}

starplot/models/milky_way.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+
+import pyarrow as pa
+from shapely import Polygon, MultiPolygon
+
+from starplot.models.base import SkyObject, CatalogObject
+
+
+@dataclass(slots=True, kw_only=True)
+class MilkyWay(CatalogObject, SkyObject):
+    """
+    Milky Way model.
+    """
+
+    geometry: Polygon | MultiPolygon
+    """Shapely Polygon of the Milky Way's extent. Right ascension coordinates are in degrees (0...360)."""
+
+    @classmethod
+    def _pyarrow_schema(cls):
+        base_schema = super(MilkyWay, cls)._pyarrow_schema()
+        extra_fields = [
+            pa.field("pk", pa.int64(), nullable=False),
+            pa.field("geometry", pa.binary(), nullable=False),
+        ]
+        return pa.schema(list(base_schema) + extra_fields)
+
+
+def from_tuple(d: tuple) -> MilkyWay:
+    kwargs = {f: getattr(d, f) for f in MilkyWay._fields() if hasattr(d, f)}
+    return MilkyWay(**kwargs)

starplot/models/moon.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+
+import numpy as np
+from shapely import Polygon
+from skyfield.api import Angle
+from skyfield import almanac
+
+from starplot.data import load
+from starplot.models.observer import Observer
+from starplot.models.base import SkyObject
+from starplot.geometry import circle
+
+
+class MoonPhase(str, Enum):
+    """Phases of Earth's moon"""
+
+    NEW_MOON = "New Moon"
+    WAXING_CRESCENT = "Waxing Crescent"
+    FIRST_QUARTER = "First Quarter"
+    WAXING_GIBBOUS = "Waxing Gibbous"
+    FULL_MOON = "Full Moon"
+    WANING_GIBBOUS = "Waning Gibbous"
+    LAST_QUARTER = "Last Quarter"
+    WANING_CRESCENT = "Waning Crescent"
+
+
+@dataclass(slots=True, kw_only=True)
+class Moon(SkyObject):
+    """Moon model. Only used for Earth's moon right now, but will potentially represent other planets' moons in future versions."""
+
+    name: str = "Moon"
+    """Name of the moon"""
+
+    dt: datetime = None
+    """Date/time of moon's position"""
+
+    apparent_size: float
+    """Apparent diameter in the sky (degrees)"""
+
+    phase_angle: float
+    """Angle of the moon from the Sun (degrees)"""
+
+    phase_description: str
+    """Description of the moon's phase. The Moon will be considered New/Full/Quarter if it's within 12 hours of that precise phase."""
+
+    illumination: float
+    """Percent of illumination (0 to 1)"""
+
+    geometry: Polygon = None
+    """Shapely Polygon of the moon's extent. Right ascension coordinates are in degrees (0 to 360)."""
+
+    @classmethod
+    def get(
+        cls,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+    ) -> "Moon":
+        """
+        Get the Moon for a specific date/time and observing location.
+
+        Args:
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating moon positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+        """
+        RADIUS_KM = 1_740
+
+        observer = observer or Observer(lat=None, lon=None)
+        timescale = observer.timescale
+
+        eph = load(ephemeris)
+        moon = eph["moon"]
+
+        ra, dec, distance = observer._astrometric(moon, ephemeris=ephemeris)
+
+        apparent_diameter_degrees = Angle(
+            radians=np.arcsin(RADIUS_KM / distance.km) * 2.0
+        ).degrees
+
+        phase_angle = almanac.moon_phase(eph, timescale).degrees
+
+        if phase_angle <= 180:
+            illumination = phase_angle / 180
+        else:
+            illumination = 2 - (phase_angle / 180)
+
+        # phase angle 12 hours BEFORE dt
+        phase_angle_0 = almanac.moon_phase(eph, timescale - timedelta(hours=12)).degrees
+
+        # phase angle 12 hours AFTER dt
+        phase_angle_1 = almanac.moon_phase(eph, timescale + timedelta(hours=12)).degrees
+
+        phase = None
+
+        if phase_angle_1 < phase_angle_0:
+            phase = MoonPhase.NEW_MOON
+
+        elif phase_angle_0 < 90 < phase_angle_1:
+            phase = MoonPhase.FIRST_QUARTER
+
+        elif phase_angle_0 < 180 < phase_angle_1:
+            phase = MoonPhase.FULL_MOON
+
+        elif phase_angle_0 < 270 < phase_angle_1:
+            phase = MoonPhase.LAST_QUARTER
+
+        elif 0 < phase_angle < 90:
+            phase = MoonPhase.WAXING_CRESCENT
+
+        elif 90 < phase_angle < 180:
+            phase = MoonPhase.WAXING_GIBBOUS
+
+        elif 180 < phase_angle < 270:
+            phase = MoonPhase.WANING_GIBBOUS
+
+        elif 270 < phase_angle < 360:
+            phase = MoonPhase.WANING_CRESCENT
+
+        return Moon(
+            ra=ra.hours * 15,
+            dec=dec.degrees,
+            name="Moon",
+            dt=observer.dt,
+            apparent_size=apparent_diameter_degrees,
+            phase_angle=phase_angle,
+            phase_description=phase.value,
+            illumination=illumination,
+            geometry=circle((ra.hours * 15, dec.degrees), apparent_diameter_degrees),
+        )

starplot/models/objects.py

@@ -0,0 +1,29 @@
+from starplot.models import Star, DSO, Moon, Sun, Planet, Constellation
+
+
+class ObjectList(object):
+    """Lists of objects that have been plotted. An instance of this model is returned by a plot's `objects` property."""
+
+    stars: list[Star] = None
+    """Stars"""
+
+    constellations: list[Constellation] = None
+    """Constellations"""
+
+    dsos: list[DSO] = None
+    """Deep Sky Objects (DSOs)"""
+
+    planets: list[Planet] = None
+    """Planets"""
+
+    moon: Moon = None
+    """Moon"""
+
+    sun: Sun = None
+    """Sun"""
+
+    def __init__(self, *args, **kwargs) -> None:
+        self.stars = []
+        self.dsos = []
+        self.planets = []
+        self.constellations = []

starplot/models/observer.py

@@ -0,0 +1,125 @@
+from datetime import datetime, timezone
+from functools import cached_property, cache
+from typing import Callable
+
+
+from pydantic import BaseModel, AwareDatetime, Field, computed_field
+from skyfield.timelib import Timescale
+from skyfield.api import wgs84, Star as SkyfieldStar
+
+from starplot.data import load
+
+ts = load.timescale()
+
+
+class Observer(BaseModel):
+    """
+    Represents an observer at a specific time and place.
+
+    Example:
+
+    ```python
+    obs = Observer(
+        dt=datetime(2025, 10, 13, 21, 0, 0, tzinfo=ZoneInfo('US/Pacific')),
+        lat=33.363484,
+        lon=-116.836394,
+    )
+    ```
+    """
+
+    dt: AwareDatetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    """
+    Date and time of observation (**must be timezone-aware**).
+    
+    Defaults to current time in UTC.
+    """
+
+    lat: float | None = Field(default=0, ge=-90, le=90)
+    """Latitude of observer location"""
+
+    lon: float | None = Field(default=0, ge=-180, le=180)
+    """Longitude of observer location"""
+
+    elevation: float = 0
+    """Elevation of observer, in meters"""
+
+    temperature: float = 10
+    """Temperature in degrees Celsius. This is only used for determining atmospheric refraction for apparent positions."""
+
+    pressure: float | None = None
+    """Atmospheric pressure in millibars. If `None`, then it'll be estimated based on the observer's elevation. This is only used for determining atmospheric refraction for apparent positions."""
+
+    class Config:
+        frozen = True
+        arbitrary_types_allowed = True
+
+    @computed_field
+    @cached_property
+    def timescale(self) -> Timescale:
+        """
+        **Read-only Property**
+
+        Timescale instance of the specified datetime (used by Skyfield)
+        """
+        return ts.from_datetime(self.dt)
+
+    @computed_field
+    @cached_property
+    def lst(self) -> float:
+        """
+        **Read-only Property**
+
+        Local sidereal time (in degrees)
+        """
+        return float(360.0 * self.timescale.gmst / 24.0 + self.lon) % 360.0
+
+    @computed_field
+    @cached_property
+    def has_location(self) -> bool:
+        return self.lat is not None and self.lon is not None
+
+    @classmethod
+    def at_epoch(cls, epoch: float) -> "Observer":
+        """
+        Returns an Observer for the specified epoch (Julian year)
+        """
+        return Observer(dt=ts.J(epoch).utc_datetime())
+
+    @cache
+    def position(self, ephemeris: str = "de421.bsp"):
+        """
+        Returns a Skyfield position for this observer.
+
+        If the observer has no lat/lon, then the Earth's center will be returned.
+
+        Args:
+            ephemeris: Ephemeris to use
+        """
+        eph = load(ephemeris)
+        earth = eph["earth"]
+
+        if self.lat is None and self.lon is None:
+            return earth
+
+        return earth + wgs84.latlon(self.lat, self.lon, self.elevation)
+
+    @cache
+    def observe(self, ephemeris: str = "de421.bsp") -> Callable:
+        return self.position(ephemeris).at(self.timescale).observe
+
+    def _astrometric(self, obj: SkyfieldStar, ephemeris: str = "de421.bsp"):
+        ra, dec, distance = self.observe(ephemeris)(obj).radec()
+        return ra, dec, distance
+
+    def _apparent(self, obj: SkyfieldStar, ephemeris: str = "de421.bsp"):
+        """Returns apparent AZ, ALT of object"""
+        pressure_mbar = self.pressure if self.pressure is not None else "standard"
+        pos_alt, pos_az, _ = (
+            self.observe(ephemeris)(obj)
+            .apparent()
+            .altaz(
+                temperature_C=self.temperature,
+                pressure_mbar=pressure_mbar,
+            )
+        )
+        return pos_az.degrees, pos_alt.degrees