starplot 0.15.8__py2.py3-none-any.whl → 0.16.1__py2.py3-none-any.whl

starplot/__init__.py

@@ -1,11 +1,12 @@
 """Star charts and maps of the sky"""
 
-__version__ = "0.15.8"
+__version__ = "0.16.1"
 
 from .base import BasePlot  # noqa: F401
-from .map import MapPlot, Projection  # noqa: F401
+from .map import MapPlot  # noqa: F401
 from .horizon import HorizonPlot  # noqa: F401
 from .optic import OpticPlot  # noqa: F401
+from .zenith import ZenithPlot  # noqa: F401
 from .models import (
     DSO,  # noqa: F401
     DsoType,  # noqa: F401
@@ -17,4 +18,8 @@ from .models import (
     ObjectList,  # noqa: F401
 )
 from .styles import *  # noqa: F401 F403
+from .observer import Observer  # noqa: F401
+from .projections import *  # noqa: F401 F403
+from .config import settings  # noqa: F401
+
 from ibis import _  # noqa: F401 F403

starplot/base.py

@@ -1,5 +1,4 @@
 from abc import ABC, abstractmethod
-from datetime import datetime
 from typing import Dict, Union, Optional
 from random import randrange
 import logging
@@ -8,27 +7,29 @@ import numpy as np
 import rtree
 from matplotlib import patches
 from matplotlib import pyplot as plt, patheffects
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
 from matplotlib.lines import Line2D
-from pytz import timezone
 from shapely import Polygon, Point
 
 from starplot.coordinates import CoordinateSystem
 from starplot import geod, models, warnings
+from starplot.config import settings, SvgTextType
 from starplot.data import load, ecliptic
 from starplot.models.planet import PlanetName, PLANET_LABELS_DEFAULT
 from starplot.models.moon import MoonPhase
+from starplot.observer import Observer
 from starplot.styles import (
     AnchorPointEnum,
     PlotStyle,
     MarkerStyle,
     ObjectStyle,
     LabelStyle,
-    LegendLocationEnum,
-    LegendStyle,
     LineStyle,
     MarkerSymbolEnum,
     PathStyle,
     PolygonStyle,
+    GradientDirection,
     fonts,
 )
 from starplot.styles.helpers import use_style
@@ -67,10 +68,28 @@ class BasePlot(ABC):
     _background_clip_path = None
     _clip_path_polygon: Polygon = None  # clip path in display coordinates
     _coordinate_system = CoordinateSystem.RA_DEC
+    _gradient_direction: GradientDirection = GradientDirection.LINEAR
+
+    ax: Axes
+    """
+    The underlying [Matplotlib axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes) that everything is plotted on.
+    
+    **Important**: Most Starplot plotting functions also specify a transform based on the plot's projection when plotting things on the Matplotlib Axes instance, so use this property at your own risk!
+    """
+
+    fig: Figure
+    """
+    The underlying [Matplotlib figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure) that the axes is drawn on.
+    """
+
+    style: PlotStyle
+    """
+    The plot's style.
+    """
 
     def __init__(
         self,
-        dt: datetime = None,
+        observer: Observer = Observer(),
         ephemeris: str = "de421_2001.bsp",
         style: PlotStyle = DEFAULT_STYLE,
         resolution: int = 4096,
@@ -81,6 +100,11 @@ class BasePlot(ABC):
         *args,
         **kwargs,
     ):
+        if settings.svg_text_type == SvgTextType.PATH:
+            plt.rcParams["svg.fonttype"] = "path"
+        else:
+            plt.rcParams["svg.fonttype"] = "none"
+
         px = 1 / DPI  # plt.rcParams["figure.dpi"]  # pixel in inches
         self.pixels_per_point = DPI / 72
 
@@ -97,7 +121,7 @@ class BasePlot(ABC):
         if suppress_warnings:
             warnings.suppress()
 
-        self.dt = dt or timezone("UTC").localize(datetime.now())
+        self.observer = observer
         self._ephemeris_name = ephemeris
         self.ephemeris = load(ephemeris)
         self.earth = self.ephemeris["earth"]
@@ -121,7 +145,6 @@ class BasePlot(ABC):
             linewidth=self.style.text_border_width * self.scale,
             foreground=self.style.text_border_color.as_hex(),
         )
-        self.timescale = load.timescale().from_datetime(self.dt)
 
         self._objects = models.ObjectList()
         self._labeled_stars = []
@@ -359,7 +382,10 @@ class BasePlot(ABC):
             return None
 
         x, y = self._prepare_coords(ra, dec)
-        kwargs["path_effects"] = kwargs.get("path_effects", [self.text_border])
+
+        if settings.svg_text_type == SvgTextType.PATH:
+            kwargs["path_effects"] = kwargs.get("path_effects", [self.text_border])
+
         remove_on_constellation_collision = kwargs.pop(
             "remove_on_constellation_collision", True
         )
@@ -495,6 +521,14 @@ class BasePlot(ABC):
             elif label is not None:
                 label.remove()
 
+    @property
+    def magnitude_range(self) -> tuple[float, float]:
+        """
+        Range of magnitude for all plotted stars, as a tuple (min, max)
+        """
+        mags = [s.magnitude for s in self.objects.stars]
+        return (min(mags), max(mags))
+
     @use_style(LabelStyle)
     def text(
         self,
@@ -510,7 +544,7 @@ class BasePlot(ABC):
 
         Args:
             text: Text to plot
-            ra: Right ascension of text (0...24)
+            ra: Right ascension of text (0...360)
             dec: Declination of text (-90...90)
             style: Styling of the text
             hide_on_collision: If True, then the text will not be plotted if it collides with another label
@@ -574,51 +608,6 @@ class BasePlot(ABC):
         style_kwargs["pad"] = style.line_spacing
         self.ax.set_title(text, **style_kwargs)
 
-    @use_style(LegendStyle, "legend")
-    def legend(self, style: LegendStyle = None):
-        """
-        Plots the legend.
-
-        If the legend is already plotted, then it'll be removed first and then plotted again. So, it's safe to call this function multiple times if you need to 'refresh' the legend.
-
-        Args:
-            style: Styling of the legend. If None, then the plot's style (specified when creating the plot) will be used
-        """
-        if self._legend is not None:
-            self._legend.remove()
-
-        if not self._legend_handles:
-            return
-
-        bbox_kwargs = {}
-
-        if style.location == LegendLocationEnum.OUTSIDE_BOTTOM:
-            style.location = "lower center"
-            offset_y = -0.08
-            if getattr(self, "_axis_labels", False):
-                offset_y -= 0.05
-            bbox_kwargs = dict(
-                bbox_to_anchor=(0.5, offset_y),
-            )
-
-        elif style.location == LegendLocationEnum.OUTSIDE_TOP:
-            style.location = "upper center"
-            offset_y = 1.08
-            if getattr(self, "_axis_labels", False):
-                offset_y += 0.05
-            bbox_kwargs = dict(
-                bbox_to_anchor=(0.5, offset_y),
-            )
-
-        self._legend = self.ax.legend(
-            handles=self._legend_handles.values(),
-            **style.matplot_kwargs(self.scale),
-            **bbox_kwargs,
-        ).set_zorder(
-            # zorder is not a valid kwarg to legend(), so we have to set it afterwards
-            style.zorder
-        )
-
     def close_fig(self) -> None:
         """Closes the underlying matplotlib figure."""
         if self.fig:
@@ -674,7 +663,7 @@ class BasePlot(ABC):
         # Plot marker
         x, y = self._prepare_coords(ra, dec)
         style_kwargs = style.marker.matplot_scatter_kwargs(self.scale)
-        self.ax.scatter(
+        result = self.ax.scatter(
             x,
             y,
             **style_kwargs,
@@ -722,7 +711,7 @@ class BasePlot(ABC):
             )
 
         if legend_label is not None:
-            self._add_legend_handle_marker(legend_label, style.marker)
+            self._legend_handles[legend_label] = result
 
     @use_style(ObjectStyle, "planets")
     def planets(
@@ -744,7 +733,9 @@ class BasePlot(ABC):
             legend_label: How to label the planets in the legend. If `None`, then the planets will not be added to the legend
         """
         labels = labels or {}
-        planets = models.Planet.all(self.dt, self.lat, self.lon, self._ephemeris_name)
+        planets = models.Planet.all(
+            self.observer.dt, self.observer.lat, self.observer.lon, self._ephemeris_name
+        )
 
         for p in planets:
             label = labels.get(p.name)
@@ -798,7 +789,10 @@ class BasePlot(ABC):
             legend_label: How the sun will be labeled in the legend
         """
         s = models.Sun.get(
-            dt=self.dt, lat=self.lat, lon=self.lon, ephemeris=self._ephemeris_name
+            dt=self.observer.dt,
+            lat=self.observer.lat,
+            lon=self.observer.lon,
+            ephemeris=self._ephemeris_name,
         )
         s.name = label or s.name
 
@@ -909,7 +903,7 @@ class BasePlot(ABC):
         if geometry is not None:
             points = list(zip(*geometry.exterior.coords.xy))
 
-        self._polygon(points, style, gid=kwargs.get("gid") or "polygon")
+        self._polygon(points, style, gid=kwargs.get("gid") or "polygon", **kwargs)
 
         if legend_label is not None:
             self._add_legend_handle_marker(
@@ -1073,7 +1067,10 @@ class BasePlot(ABC):
             label: How the Moon will be labeled on the plot and legend
         """
         m = models.Moon.get(
-            dt=self.dt, lat=self.lat, lon=self.lon, ephemeris=self._ephemeris_name
+            dt=self.observer.dt,
+            lat=self.observer.lat,
+            lon=self.observer.lon,
+            ephemeris=self._ephemeris_name,
         )
         m.name = label or m.name
 

starplot/cli.py

@@ -6,7 +6,7 @@ COMMANDS = ["setup"]
 
 
 def setup(options):
-    from starplot import settings
+    from starplot.config import settings
     from starplot.data import db, bigsky
 
     print("Installing DuckDB spatial extension...")
@@ -16,11 +16,11 @@ def setup(options):
 
     fonts.load()
 
-    print(f"Installed to: {settings.DUCKDB_EXTENSION_PATH}")
+    print(f"Installed to: {settings.duckdb_extension_path}")
 
     if "--install-big-sky" in options:
         bigsky.download_if_not_exists()
-        print(f"Big Sky Catalog downloaded and installed to: {settings.DOWNLOAD_PATH}")
+        print(f"Big Sky Catalog downloaded and installed to: {settings.download_path}")
 
 
 def main():

starplot/config.py

@@ -0,0 +1,56 @@
+from enum import Enum
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+STARPLOT_PATH = Path(__file__).resolve().parent
+"""Path of starplot source"""
+
+DATA_PATH = STARPLOT_PATH / "data" / "library"
+"""Path of starplot data"""
+
+
+RAW_DATA_PATH = STARPLOT_PATH.parent.parent / "raw"
+BUILD_PATH = STARPLOT_PATH.parent.parent / "build"
+
+
+class SvgTextType(str, Enum):
+    PATH = "path"
+    ELEMENT = "element"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="STARPLOT_")
+    """Configuration for the Pydantic settings model. Do not change."""
+
+    download_path: Path = DATA_PATH / "downloads"
+    """
+    Path for downloaded data, including the Big Sky catalog, ephemeris files, etc.
+    
+    Default = `<starplot_source_path>/data/library/downloads/`
+    """
+
+    duckdb_extension_path: Path = DATA_PATH / "duckdb-extensions"
+    """
+    Path for the DuckDB spatial extension, which is required for the data backend.
+
+    Default = `<starplot_source_path>/data/library/duckdb-extensions/`
+    """
+
+    svg_text_type: SvgTextType = SvgTextType.PATH
+    """
+    Method for rendering text in SVG exports:
+
+    - `"path"` (default) will render all text as paths. This will increase the filesize, 
+    but allow all viewers to see the font correctly (even if they don't have the font 
+    installed on their system).
+
+    - `"element"` will render all text as an [SVG `<text>` element](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/text), 
+    which means the text will be editable in graphic design applications but the text may render in a system default font if the original 
+    font isn't available. **Important: when using the "element" method, text borders will be turned OFF.**
+    
+    """
+
+
+settings = Settings()

starplot/data/__init__.py

@@ -1,13 +1,13 @@
 from skyfield.api import Loader
 
-from starplot import settings
+from starplot.config import settings, DATA_PATH
 
-load = Loader(settings.DATA_PATH)
+load = Loader(DATA_PATH)
 
 
 class DataFiles:
-    BIG_SKY = settings.DOWNLOAD_PATH / "bigsky.0.4.0.stars.parquet"
+    BIG_SKY = settings.download_path / "bigsky.0.4.0.stars.parquet"
 
-    BIG_SKY_MAG11 = settings.DATA_PATH / "bigsky.0.4.0.stars.mag11.parquet"
+    BIG_SKY_MAG11 = DATA_PATH / "bigsky.0.4.0.stars.mag11.parquet"
 
-    DATABASE = settings.DATA_PATH / "sky.db"
+    DATABASE = DATA_PATH / "sky.db"

starplot/data/bigsky.py

@@ -3,7 +3,7 @@ from pathlib import Path
 
 import pandas as pd
 
-from starplot import settings
+from starplot.config import settings
 from starplot.data import DataFiles, utils
 
 
@@ -21,7 +21,7 @@ def get_url(version: str = BIG_SKY_VERSION, filename: str = BIG_SKY_FILENAME):
 
 def download(
     url: str = None,
-    download_path: str = settings.DOWNLOAD_PATH,
+    download_path: str = settings.download_path,
     download_filename: str = BIG_SKY_FILENAME,
     build_file: str = DataFiles.BIG_SKY,
 ):
@@ -102,7 +102,7 @@ def exists(path) -> bool:
 def download_if_not_exists(
     filename: str = DataFiles.BIG_SKY,
     url: str = None,
-    download_path: str = settings.DOWNLOAD_PATH,
+    download_path: str = settings.download_path,
     download_filename: str = BIG_SKY_FILENAME,
     build_file: str = DataFiles.BIG_SKY,
 ):

starplot/data/db.py

@@ -2,7 +2,7 @@ from functools import cache
 
 import ibis
 
-from starplot import settings
+from starplot.config import settings
 from starplot.data import DataFiles
 
 
@@ -12,6 +12,6 @@ def connect():
         DataFiles.DATABASE, read_only=True
     )  # , threads=2, memory_limit="1GB"
     connection.raw_sql(
-        f"SET extension_directory = '{str(settings.DUCKDB_EXTENSION_PATH)}';"
+        f"SET extension_directory = '{str(settings.duckdb_extension_path)}';"
     )
     return connection

starplot/geometry.py

@@ -95,6 +95,54 @@ def unwrap_polygon_360(polygon: Polygon) -> Polygon:
     return polygon
 
 
+def split_polygon_at_zero(polygon: Polygon) -> list[Polygon]:
+    """
+    Splits a polygon at the first point of Aries (RA=0)
+
+    Args:
+        polygon: Polygon that possibly needs splitting
+
+    Returns:
+        List of polygons
+    """
+    ra, dec = [p for p in polygon.exterior.coords.xy]
+
+    if min(ra) < 180 and max(ra) > 300:
+        new_ra = [r + 360 if r < 180 else r for r in ra]
+        new_polygon = Polygon(list(zip(new_ra, dec)))
+
+        polygon_1 = new_polygon.intersection(
+            Polygon(
+                [
+                    [0, -90],
+                    [360, -90],
+                    [360, 90],
+                    [0, 90],
+                    [0, -90],
+                ]
+            )
+        )
+
+        polygon_2 = new_polygon.intersection(
+            Polygon(
+                [
+                    [360, -90],
+                    [720, -90],
+                    [720, 90],
+                    [360, 90],
+                    [360, -90],
+                ]
+            )
+        )
+
+        p2_ra, p2_dec = [p for p in polygon_2.exterior.coords.xy]
+        p2_new_ra = [ra - 360 for ra in p2_ra]
+
+        return [polygon_1, Polygon(list(zip(p2_new_ra, p2_dec)))]
+
+    return [polygon]
+
+
 def random_point_in_polygon(
     polygon: Polygon, max_iterations: int = 100, seed: int = None
 ) -> Point: