starplot 0.20.5__py3-none-any.whl

starplot/models/optics.py

@@ -0,0 +1,342 @@
+import math
+
+from abc import ABC, abstractmethod
+
+import pyproj
+from matplotlib import patches
+from pydantic import BaseModel, computed_field
+
+from starplot.utils import in_circle
+
+
+class Optic(BaseModel, ABC):
+    """Abstract class for defining Optics."""
+
+    def __str__(self):
+        return "Optic"
+
+    @property
+    @abstractmethod
+    def xlim(self):
+        pass
+
+    @property
+    @abstractmethod
+    def ylim(self):
+        pass
+
+    @property
+    @abstractmethod
+    def label(self):
+        return "Abstract Optic"
+
+    @abstractmethod
+    def patch(self, center_x, center_y) -> patches.Patch:
+        pass
+
+    def transform(self, axis) -> None:
+        pass
+
+    @abstractmethod
+    def in_bounds(self, x, y, scale: float = 1) -> bool:
+        pass
+
+    def _compute_radius(self, radius_degrees: float, x: float = 0, y: float = 0):
+        geod = pyproj.Geod("+a=6378137 +f=0.0", sphere=True)
+        _, _, distance = geod.inv(x, y, x + radius_degrees, y)
+        return distance
+
+
+class Scope(Optic):
+    """Creates a new generic Scope optic.
+
+    Use this class to create custom scope optics or use it as a generic optic that does NOT apply any transforms to the view.
+
+    See subclasses of this optic for more specific use cases:
+
+    - [`Refractor`][starplot.models.Refractor] - automatically inverts the view (i.e. assumes a star diagonal is used)
+
+    - [`Reflector`][starplot.models.Reflector] - automatically rotates the view so it's upside-down
+
+    Args:
+        focal_length: Focal length (mm) of the telescope
+        eyepiece_focal_length: Focal length (mm) of the eyepiece
+        eyepiece_fov: Field of view (degrees) of the eyepiece
+
+    Returns:
+        Scope: A new instance of a Scope optic
+    """
+
+    focal_length: float
+    """Focal length (mm) of the telescope"""
+
+    eyepiece_focal_length: float
+    """Focal length (mm) of the eyepiece"""
+
+    eyepiece_fov: float
+    """Field of view (degrees) of the eyepiece"""
+
+    @computed_field
+    @property
+    def magnification(self) -> float:
+        """Magnification calculated from the telescope's focal length and eyepiece focal length"""
+        return self.focal_length / self.eyepiece_focal_length
+
+    @computed_field
+    @property
+    def true_fov(self) -> float:
+        """True field of view of telescope"""
+        return self.eyepiece_fov / self.magnification
+
+    @computed_field
+    @property
+    def radius(self) -> float:
+        return self._compute_radius(self.true_fov / 2)
+
+    def __str__(self):
+        return f"{self.focal_length:.0f}mm w/ {self.eyepiece_focal_length:.0f}mm ({self.magnification:.0f}x) @  {self.eyepiece_fov:.0f}\N{DEGREE SIGN} = {self.true_fov:.2f}\N{DEGREE SIGN} TFOV"
+
+    @property
+    def xlim(self):
+        return self.radius
+
+    @property
+    def ylim(self):
+        return self.radius
+
+    @property
+    def label(self):
+        return "Scope"
+
+    def patch(self, center_x, center_y, **kwargs):
+        padding = kwargs.pop("padding", 0)
+        return patches.Circle(
+            (center_x, center_y),
+            radius=self.radius + padding,
+            **kwargs,
+        )
+
+    def in_bounds(self, x, y, scale: float = 1) -> bool:
+        return in_circle(x, y, 0, 0, self.radius * scale)
+
+
+class Refractor(Scope):
+    """Creates a new Refractor Telescope optic
+
+    Warning:
+        This optic assumes a star diagonal is used, so it applies a transform that inverts the image.
+
+        If you don't want this transform applied, then use the generic [`Scope`][starplot.models.Scope] optic instead.
+
+    Args:
+        focal_length: Focal length (mm) of the telescope
+        eyepiece_focal_length: Focal length (mm) of the eyepiece
+        eyepiece_fov: Field of view (degrees) of the eyepiece
+
+    Returns:
+        Refractor: A new instance of a Refractor optic
+
+    """
+
+    @property
+    def label(self):
+        return "Refractor"
+
+    def transform(self, axis) -> None:
+        axis.invert_xaxis()
+
+
+class Reflector(Scope):
+    """Creates a new Reflector Telescope optic
+
+    Warning:
+        This optic applies a transform that produces an "upside-down" image.
+
+        If you don't want this transform applied, then use the generic [`Scope`][starplot.models.Scope] optic instead.
+
+    Args:
+        focal_length: Focal length (mm) of the telescope
+        eyepiece_focal_length: Focal length (mm) of the eyepiece
+        eyepiece_fov: Field of view (degrees) of the eyepiece
+
+    Returns:
+        Reflector: A new instance of a Reflector optic
+
+    """
+
+    @property
+    def label(self):
+        return "Reflector"
+
+    def transform(self, axis) -> None:
+        axis.invert_xaxis()
+        axis.invert_yaxis()
+
+
+class Binoculars(Optic):
+    """Creates a new Binoculars optic
+
+    Args:
+        magnification: Magnification of the binoculars
+        fov: Apparent field of view (FOV) of the binoculars in degrees. This isn't always easy to find for binoculars, so if you can't find it in your binocular's specs, then try using `60`.
+
+    Returns:
+        Binoculars: A new instance of a Binoculars optic
+
+    """
+
+    magnification: float
+    """Magnification of the binoculars"""
+
+    fov: float
+    """Apparent field of view of the binoculars"""
+
+    @computed_field
+    @property
+    def true_fov(self) -> float:
+        """True field of view of binoculars"""
+        return self.fov / self.magnification
+
+    @computed_field
+    @property
+    def radius(self) -> float:
+        return self._compute_radius(self.true_fov / 2)
+
+    def __str__(self):
+        return f"{self.magnification:.0f}x @ {self.fov:.0f}\N{DEGREE SIGN} = {self.true_fov}\N{DEGREE SIGN}"
+
+    @property
+    def xlim(self):
+        return self.radius
+
+    @property
+    def ylim(self):
+        return self.radius
+
+    @property
+    def label(self):
+        return "Binoculars"
+
+    def patch(self, center_x, center_y, **kwargs):
+        padding = kwargs.pop("padding", 0)
+        return patches.Circle(
+            (center_x, center_y),
+            radius=self.radius + padding,
+            **kwargs,
+        )
+
+    def in_bounds(self, x, y, scale: float = 1) -> bool:
+        return in_circle(x, y, 0, 0, self.radius * scale)
+
+
+class Camera(Optic):
+    """Creates a new Camera optic
+
+    Note:
+        Field of view for each dimension is calculated using the following formula:
+
+        ```
+        TFOV = 2 * arctan( d / (2 * f) )
+        ```
+
+        _Where_:
+
+        d = sensor size (height or width)
+
+        f = focal length of lens
+
+    Args:
+        sensor_height: Height of camera sensor (mm)
+        sensor_width: Width of camera sensor (mm)
+        lens_focal_length: Focal length of camera lens (mm)
+        rotation: Angle (degrees) to rotate camera, defaults to 0
+
+    Returns:
+        Camera: A new instance of a Camera optic
+
+    """
+
+    sensor_height: float
+    """Height (mm) of camera's sensor"""
+
+    sensor_width: float
+    """Width (mm) of camera's sensor"""
+
+    lens_focal_length: float
+    """Focal length (mm) of the camera's lens"""
+
+    rotation: float = 0
+    """Angle (degrees) to rotate the camera"""
+
+    @computed_field
+    @property
+    def true_fov_x(self) -> float:
+        return 2 * math.degrees(
+            math.atan(self.sensor_width / (2 * self.lens_focal_length))
+        )
+
+    @computed_field
+    @property
+    def true_fov_y(self) -> float:
+        return 2 * math.degrees(
+            math.atan(self.sensor_height / (2 * self.lens_focal_length))
+        )
+
+    @computed_field
+    @property
+    def true_fov(self) -> float:
+        return max(self.true_fov_x, self.true_fov_y)
+
+    @computed_field
+    @property
+    def radius_x(self) -> float:
+        return self._compute_radius(self.true_fov_x / 2)
+
+    @computed_field
+    @property
+    def radius_y(self) -> float:
+        return self._compute_radius(self.true_fov_y / 2)
+
+    def __str__(self):
+        return f"{self.sensor_width}x{self.sensor_height} w/ {self.lens_focal_length:.0f}mm lens = {self.true_fov_x:.2f}\N{DEGREE SIGN} x {self.true_fov_y:.2f}\N{DEGREE SIGN}"
+
+    @property
+    def xlim(self):
+        x_offset = self.radius_x * self.rotation / 180
+        if self.rotation:
+            x_offset *= 1.1
+        return self.radius_x + x_offset
+
+    @property
+    def ylim(self):
+        y_offset = self.radius_y * math.sin(math.radians(self.rotation))
+        if self.rotation:
+            y_offset *= 1.2
+        return self.radius_y + y_offset
+
+    @property
+    def label(self):
+        return "Camera"
+
+    def patch(self, center_x, center_y, **kwargs):
+        padding = kwargs.pop("padding", 0)
+        x = center_x - self.radius_x - padding
+        y = center_y - self.radius_y - padding
+        return patches.Rectangle(
+            (x, y),
+            self.radius_x * 2 + padding,
+            self.radius_y * 2 + padding,
+            angle=self.rotation,
+            rotation_point="center",
+            **kwargs,
+        )
+
+    def in_bounds(self, x, y, scale: float = 1) -> bool:
+        radians = math.radians(180 - self.rotation)
+
+        px = x * math.cos(radians) - y * math.sin(radians)
+        py = x * math.sin(radians) + y * math.cos(radians)
+
+        in_bounds_x = px < self.radius_x * scale and px > -1 * self.radius_x * scale
+        in_bounds_y = py < self.radius_y * scale and py > -1 * self.radius_y * scale
+        return in_bounds_x and in_bounds_y

starplot/models/planet.py

@@ -0,0 +1,137 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Iterator
+
+import numpy as np
+
+from shapely import Polygon
+from skyfield.api import Angle
+
+from starplot.data import load
+from starplot.models.base import SkyObject
+from starplot.models.observer import Observer
+from starplot.geometry import circle
+
+
+class PlanetName(str, Enum):
+    """Planet names"""
+
+    MERCURY = "mercury"
+    VENUS = "venus"
+    MARS = "mars"
+    JUPITER = "jupiter"
+    SATURN = "saturn"
+    URANUS = "uranus"
+    NEPTUNE = "neptune"
+    PLUTO = "pluto"
+
+
+PLANET_LABELS_DEFAULT = {p: p.value.upper() for p in PlanetName}
+
+PLANET_RADIUS_KM = {
+    PlanetName.MERCURY: 2_440,
+    PlanetName.VENUS: 6_052,
+    PlanetName.MARS: 3_390,
+    PlanetName.JUPITER: 69_911,
+    PlanetName.SATURN: 58_232,
+    PlanetName.URANUS: 25_362,
+    PlanetName.NEPTUNE: 24_622,
+    PlanetName.PLUTO: 1_151,
+}
+"""
+Planet radii in kilometers, via NASA:
+
+- https://science.nasa.gov/resource/solar-system-sizes/
+- https://science.nasa.gov/dwarf-planets/pluto/facts/
+
+Retrieved on 18-APR-2024
+"""
+
+
+@dataclass(slots=True, kw_only=True)
+class Planet(SkyObject):
+    """Planet model."""
+
+    name: str = None
+    """
+    Name of the planet:
+
+    - Mercury
+    - Venus
+    - Mars
+    - Jupiter
+    - Saturn
+    - Uranus
+    - Neptune
+    - Pluto
+    
+    """
+
+    dt: datetime = None
+    """Date/time of planet's position"""
+
+    apparent_size: float = 0
+    """Apparent diameter (degrees)"""
+
+    geometry: Polygon = None
+    """Shapely Polygon of the planet's extent. Right ascension coordinates are in degrees (0...360)."""
+
+    @classmethod
+    def all(
+        cls,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+    ) -> Iterator["Planet"]:
+        """
+        Iterator for getting all planets at a specific date/time and observing location.
+
+        Args:
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating planet positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+        """
+
+        observer = observer or Observer(lat=None, lon=None)
+        eph = load(ephemeris)
+
+        for p in PlanetName:
+            planet = eph[f"{p.value} barycenter"]
+            ra, dec, distance = observer._astrometric(planet, ephemeris=ephemeris)
+
+            # angular diameter:
+            # https://rhodesmill.org/skyfield/examples.html#what-is-the-angular-diameter-of-a-planet-given-its-radius
+            apparent_diameter_degrees = Angle(
+                radians=np.arcsin(PLANET_RADIUS_KM[p] / distance.km) * 2.0
+            ).degrees
+
+            yield Planet(
+                ra=ra.hours * 15,
+                dec=dec.degrees,
+                name=p,
+                dt=observer.dt,
+                apparent_size=apparent_diameter_degrees,
+                geometry=circle(
+                    (ra.hours * 15, dec.degrees), apparent_diameter_degrees
+                ),
+            )
+
+    @classmethod
+    def get(
+        cls,
+        name: str,
+        observer: Observer = None,
+        ephemeris: str = "de421.bsp",
+    ) -> "Planet":
+        """
+        Get a planet for a specific date/time.
+
+        Args:
+            name: Name of the planet you want to get (see [`Planet.name`][starplot.Planet.name] for options). Case insensitive.
+            observer: Observer instance that specifies a time and location
+            ephemeris: Ephemeris to use for calculating planet positions (see [Skyfield's documentation](https://rhodesmill.org/skyfield/planets.html) for details)
+        """
+        for p in cls.all(observer, ephemeris):
+            if p.name.lower() == name.lower():
+                return p
+
+        return None

starplot/models/satellite.py

@@ -0,0 +1,138 @@
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Iterator
+
+from shapely import Point
+from skyfield.api import wgs84, EarthSatellite
+
+from starplot.data import load
+from starplot.models.base import SkyObject
+from starplot.models.observer import Observer
+
+ts = load.timescale()
+
+
+@dataclass(slots=True, kw_only=True)
+class Satellite(SkyObject):
+    """
+    Satellites can be created in two ways:
+
+    1. [`from_tle`][starplot.Satellite.from_tle] (two-line element set)
+    2. [`from_json`][starplot.Satellite.from_json] (CelesTrak JSON)
+
+    """
+
+    name: str = None
+    """Name of the satellite"""
+
+    observer: Observer = None
+    """Observer of this satellite instance"""
+
+    distance: float | None = None
+    """Distance to satellite, in Astronomical units (the Earth-Sun distance of 149,597,870,700 m)"""
+
+    geometry: Point = None
+    """Shapely Point of the satellite's position. Right ascension coordinates are in degrees (0...360)."""
+
+    _satellite: EarthSatellite = None
+
+    @classmethod
+    def from_json(
+        cls,
+        data: dict,
+        observer: Observer = None,
+    ) -> "Satellite":
+        """
+        Get a satellite for a specific date/time/location from a CelesTrak JSON.
+
+        Args:
+            data: Dictionary of the CelesTrak JSON
+            observer: Observer instance that specifies a time and location
+        """
+        observer = observer or Observer()
+        return get_satellite_at_date_location(
+            satellite=EarthSatellite.from_omm(ts, data),
+            observer=observer,
+        )
+
+    @classmethod
+    def from_tle(
+        cls,
+        name: str,
+        line1: str,
+        line2: str,
+        observer: Observer = None,
+    ) -> "Satellite":
+        """
+        Get a satellite for a specific date/time/location from a two-line element set (TLE).
+
+        Args:
+            name: Name of the satellite
+            line1: Line 1 of the two-line element set (TLE)
+            line2: Line 2 of the two-line element set (TLE)
+            observer: Observer instance that specifies a time and location
+
+        """
+        observer = observer or Observer()
+        return get_satellite_at_date_location(
+            satellite=EarthSatellite(
+                line1,
+                line2,
+                name,
+                ts,
+            ),
+            observer=observer,
+        )
+
+    def trajectory(
+        self, date_start: datetime, date_end: datetime, step: timedelta = None
+    ) -> Iterator["Satellite"]:
+        """
+        Iterator for getting a trajectory of the satellite.
+
+        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 Satellite instance at each step in the date range
+        """
+        dt = date_start
+        step = step or timedelta(hours=1)
+
+        while dt < date_end:
+            observer_kwargs = self.observer.model_dump()
+            observer_kwargs["dt"] = dt
+            new_observer = Observer(**observer_kwargs)
+            yield get_satellite_at_date_location(
+                satellite=self._satellite, observer=new_observer
+            )
+            dt += step
+
+
+def get_satellite_at_date_location(
+    satellite: EarthSatellite, observer: Observer
+) -> Satellite:
+    t = observer.timescale
+    lat = observer.lat
+    lon = observer.lon
+
+    if lat is not None and lon is not None:
+        position = wgs84.latlon(lat, lon, observer.elevation)
+        difference = satellite - position
+        topocentric = difference.at(t)
+        ra, dec, distance = topocentric.radec()
+    else:
+        ra, dec, distance = satellite.at(t).radec()
+
+    result = Satellite(
+        name=satellite.name,
+        ra=ra.hours * 15,
+        dec=dec.degrees,
+        observer=observer,
+        distance=distance.au,
+        geometry=Point(ra.hours * 15, dec.degrees),
+    )
+    setattr(result, "_satellite", satellite)
+    return result