starplot 0.10.1__py2.py3-none-any.whl → 0.11.0__py2.py3-none-any.whl

starplot/__init__.py

@@ -1,9 +1,17 @@
 """Star charts and maps"""
 
-__version__ = "0.10.1"
+__version__ = "0.11.0"
 
 from .base import BasePlot  # noqa: F401
 from .map import MapPlot, Projection  # noqa: F401
-from .models import DSO, Star, Planet, Moon, Sun, ObjectList  # noqa: F401
+from .models import (
+    DSO,  # noqa: F401
+    Star,  # noqa: F401
+    Constellation,  # noqa: F401
+    Planet,  # noqa: F401
+    Moon,  # noqa: F401
+    Sun,  # noqa: F401
+    ObjectList,  # noqa: F401
+)
 from .optic import OpticPlot  # noqa: F401
 from .styles import *  # noqa: F401 F403

starplot/base.py

@@ -22,6 +22,7 @@ from starplot.styles import (
     LabelStyle,
     LegendLocationEnum,
     LegendStyle,
+    MarkerSymbolEnum,
     PathStyle,
     PolygonStyle,
 )
@@ -143,12 +144,20 @@ class BasePlot(ABC):
                 label=label,
             )
 
-    def _text(self, ra: float, dec: float, text: str, *args, **kwargs) -> None:
+    def _text(
+        self,
+        ra: float,
+        dec: float,
+        text: str,
+        hide_on_collision: bool = True,
+        *args,
+        **kwargs,
+    ) -> None:
         if not text:
             return
 
         x, y = self._prepare_coords(ra, dec)
-        kwargs["path_effects"] = kwargs.get("path_effects") or [self.text_border]
+        kwargs["path_effects"] = kwargs.get("path_effects", [self.text_border])
         label = self.ax.annotate(
             text,
             (x, y),
@@ -156,13 +165,24 @@ class BasePlot(ABC):
             **kwargs,
             **self._plot_kwargs(),
         )
+        if kwargs.get("clip_on") is False:
+            return
+
         label.set_clip_on(True)
         label.set_clip_path(self._background_clip_path)
 
-        self._maybe_remove_label(label)
+        if hide_on_collision:
+            self._maybe_remove_label(label)
 
     @use_style(LabelStyle)
-    def text(self, text: str, ra: float, dec: float, style: LabelStyle = None):
+    def text(
+        self,
+        text: str,
+        ra: float,
+        dec: float,
+        style: LabelStyle = None,
+        hide_on_collision: bool = True,
+    ):
         """
         Plots text
 
@@ -171,6 +191,7 @@ class BasePlot(ABC):
             ra: Right ascension of text (0...24)
             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
         """
         style = style or LabelStyle()
         self._text(
@@ -178,6 +199,7 @@ class BasePlot(ABC):
             dec,
             text,
             **style.matplot_kwargs(self._size_multiplier),
+            hide_on_collision=hide_on_collision,
             xytext=(style.offset_x, style.offset_y),
             textcoords="offset pixels",
         )
@@ -213,30 +235,33 @@ class BasePlot(ABC):
         Args:
             style: Styling of the legend. If None, then the plot's style (specified when creating the plot) will be used
         """
-        if not self._legend_handles:
-            return
-
         if self._legend is not None:
             self._legend.remove()
 
+        if not self._legend_handles:
+            return
+
         bbox_kwargs = {}
 
         if style.location == LegendLocationEnum.OUTSIDE_BOTTOM:
-            # to plot legends outside the map area, you have to target the figure
-            target = self.fig
+            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, 0.13), bbox_transform=self.fig.transFigure
+                bbox_to_anchor=(0.5, offset_y),
             )
 
         elif style.location == LegendLocationEnum.OUTSIDE_TOP:
-            target = self.fig
+            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, 0.87), bbox_transform=self.fig.transFigure
+                bbox_to_anchor=(0.5, offset_y),
             )
-        else:
-            target = self.ax
 
-        self._legend = target.legend(
+        self._legend = self.ax.legend(
             handles=self._legend_handles.values(),
             **style.matplot_kwargs(size_multiplier=self._size_multiplier),
             **bbox_kwargs,
@@ -267,7 +292,7 @@ class BasePlot(ABC):
 
         Args:
             filename: Filename of exported file
-            format: Format of file: "png" or "svg"
+            format: Format of file (options are "png", "jpeg", or "svg")
             padding: Padding (in inches) around the image
             **kwargs: Any keyword arguments to pass through to matplotlib's `savefig` method
 
@@ -388,7 +413,7 @@ class BasePlot(ABC):
 
         Args:
             style: Styling of the Sun. If None, then the plot's style (specified when creating the plot) will be used
-            true_size: If True, then the Sun's true apparent size in the sky will be plotted. If False, then the style's marker size will be used.
+            true_size: If True, then the Sun's true apparent size in the sky will be plotted as a circle (the marker style's symbol will be ignored). If False, then the style's marker size will be used.
             label: How the Sun will be labeled on the plot and legend
         """
         s = models.Sun.get(
@@ -413,6 +438,7 @@ class BasePlot(ABC):
                 style=polygon_style,
             )
 
+            style.marker.symbol = MarkerSymbolEnum.CIRCLE
             self._add_legend_handle_marker(legend_label, style.marker)
 
             if label:
@@ -584,7 +610,7 @@ class BasePlot(ABC):
 
         Args:
             style: Styling of the Moon. If None, then the plot's style (specified when creating the plot) will be used
-            true_size: If True, then the Moon's true apparent size in the sky will be plotted. If False, then the style's marker size will be used.
+            true_size: If True, then the Moon's true apparent size in the sky will be plotted as a circle (the marker style's symbol will be ignored). If False, then the style's marker size will be used.
             show_phase: If True, and if `true_size = True`, then the approximate phase of the moon will be illustrated. The dark side of the moon will be colored with the marker's `edge_color`.
             label: How the Moon will be labeled on the plot and legend
         """
@@ -620,6 +646,7 @@ class BasePlot(ABC):
                     style=polygon_style,
                 )
 
+            style.marker.symbol = MarkerSymbolEnum.CIRCLE
             self._add_legend_handle_marker(legend_label, style.marker)
 
             if label:

starplot/data/__init__.py

@@ -1,3 +1,5 @@
+import os
+
 from enum import Enum
 from pathlib import Path
 
@@ -9,12 +11,21 @@ DATA_PATH = HERE / "library"
 load = Loader(DATA_PATH)
 
 
+def env(name, default):
+    return os.environ.get(name) or default
+
+
 class DataFiles(str, Enum):
+    # Built-In Files
     CONSTELLATION_LINES = DATA_PATH / "constellation_lines_inv.gpkg"
     CONSTELLATION_LINES_HIP = DATA_PATH / "constellation_lines_hips.json"
     CONSTELLATION_BORDERS = DATA_PATH / "constellation_borders_inv.gpkg"
     MILKY_WAY = DATA_PATH / "milkyway.gpkg"
     HIPPARCOS = DATA_PATH / "stars.hipparcos.parquet"
-    TYCHO_1 = DATA_PATH / "stars.tycho-1.gz.parquet"
+    BIG_SKY_MAG11 = DATA_PATH / "stars.bigsky.mag11.parquet"
     ONGC = DATA_PATH / "ongc.gpkg.zip"
     CONSTELLATIONS = DATA_PATH / "constellations.gpkg"
+
+    # Downloaded Files
+    _DOWNLOAD_PATH = Path(env("STARPLOT_DOWNLOAD_PATH", str(DATA_PATH)))
+    BIG_SKY = _DOWNLOAD_PATH / "stars.bigsky.parquet"

starplot/data/bigsky.py

@@ -0,0 +1,97 @@
+import os
+
+import pandas as pd
+
+from starplot.data import DATA_PATH, DataFiles, utils
+
+
+BIG_SKY_VERSION = "0.1.0"
+
+BIG_SKY_FILENAME = "bigsky.stars.csv.gz"
+
+BIG_SKY_URL = f"https://github.com/steveberardi/bigsky/releases/download/v{BIG_SKY_VERSION}/{BIG_SKY_FILENAME}"
+
+DOWNLOADED_PATH = DATA_PATH / BIG_SKY_FILENAME
+
+DIGITS = 4
+
+BIG_SKY_ASSETS = {
+    DataFiles.BIG_SKY: "bigsky.stars.csv.gz",
+    DataFiles.BIG_SKY_MAG11: "bigsky.stars.mag11.csv.gz",
+}
+
+
+def url(filename: str, version: str):
+    return f"https://github.com/steveberardi/bigsky/releases/download/v{version}/{filename}"
+
+
+def download(
+    filename: str = BIG_SKY_FILENAME,
+    version: str = BIG_SKY_VERSION,
+    download_path: str = None,
+    digits: int = 4,
+):
+    download_path = download_path or str(DATA_PATH / filename)
+    utils.download(
+        url(filename, version),
+        download_path,
+        "Big Sky Star Catalog",
+    )
+    to_parquet(
+        download_path,
+        DataFiles.BIG_SKY,
+        digits,
+    )
+
+
+def to_parquet(source_path: str, destination_path: str, digits: int = DIGITS):
+    print("Preparing Big Sky Catalog for Starplot...")
+
+    df = pd.read_csv(
+        source_path,
+        header=0,
+        names=[
+            "tyc_id",
+            "hip_id",
+            "ccdm",
+            "magnitude",
+            "bv",
+            "ra_degrees_j2000",
+            "dec_degrees_j2000",
+            "ra_mas_per_year",
+            "dec_mas_per_year",
+            "parallax_mas",
+        ],
+        compression="gzip",
+    )
+
+    df["ra_hours"] = df.apply(
+        lambda row: round(row.ra_degrees_j2000 / 15, digits), axis=1
+    )
+
+    df = df.assign(epoch_year=2000)
+
+    df = df.rename(
+        columns={
+            "hip_id": "hip",
+            "ra_degrees_j2000": "ra_degrees",
+            "dec_degrees_j2000": "dec_degrees",
+        }
+    )
+
+    df.to_parquet(destination_path, compression="gzip")
+
+    print(f"Done! {destination_path.value}")
+
+
+def load(path):
+    if not exists(path):
+        download(filename=BIG_SKY_ASSETS.get(path))
+
+    df = pd.read_parquet(path)
+
+    return df.set_index("tyc_id")
+
+
+def exists(path) -> bool:
+    return os.path.isfile(path)

starplot/data/stars.py

@@ -2,7 +2,7 @@ from enum import Enum
 
 from pandas import read_parquet
 
-from starplot.data import DataFiles
+from starplot.data import bigsky, DataFiles
 
 STAR_NAMES = {
     7588: "Achernar",
@@ -117,27 +117,41 @@ class StarCatalog(str, Enum):
     HIPPARCOS = "hipparcos"
     """Hipparcos Catalog = 118,218 stars"""
 
-    TYCHO_1 = "tycho-1"
-    """Tycho-1 Catalog = 1,055,115 stars"""
+    BIG_SKY_MAG11 = "big-sky-mag11"
+    """
+    [Big Sky Catalog](https://github.com/steveberardi/bigsky) ~ 900k stars up to magnitude 11
+    
+    This is an _abridged_ version of the Big Sky Catalog, including stars up to a limiting magnitude of 11 (total = 981,852).
 
+    This catalog is included with Starplot, so does not require downloading any files.
+    """
 
-def load_hipparcos():
-    return read_parquet(DataFiles.HIPPARCOS)
+    BIG_SKY = "big-sky"
+    """
+    [Big Sky Catalog](https://github.com/steveberardi/bigsky) ~ 2.5M stars
 
+    This is the full version of the Big Sky Catalog, which includes 2,557,499 stars from Hipparcos, Tycho-1, and Tycho-2.
 
-def load_tycho1():
-    df = read_parquet(DataFiles.TYCHO_1)
-    df = df.assign(
-        ra_degrees=df["ra_hours"] * 15.0,
-        epoch_year=1991.25,
-    )
-    return df.set_index("hip")
+    This catalog is very large (50+ MB), so it's not built-in to Starplot. When you plot stars and specify this catalog, the catalog 
+    will be downloaded from the [Big Sky GitHub repository](https://github.com/steveberardi/bigsky) and saved to Starplot's data library 
+    directory. You can override this download path with the environment variable `STARPLOT_DOWNLOAD_PATH`
+    
+    """
+
+
+def load_bigsky():
+    if not bigsky.exists():
+        bigsky.download()
+
+    return bigsky.load(DataFiles.BIG_SKY)
 
 
 def load(catalog: StarCatalog = StarCatalog.HIPPARCOS):
-    if catalog == StarCatalog.TYCHO_1:
-        return load_tycho1()
-    elif catalog == StarCatalog.HIPPARCOS:
-        return load_hipparcos()
+    if catalog == StarCatalog.HIPPARCOS:
+        return read_parquet(DataFiles.HIPPARCOS)
+    elif catalog == StarCatalog.BIG_SKY_MAG11:
+        return bigsky.load(DataFiles.BIG_SKY_MAG11)
+    elif catalog == StarCatalog.BIG_SKY:
+        return bigsky.load(DataFiles.BIG_SKY)
     else:
         raise ValueError("Unrecognized star catalog.")

starplot/data/utils.py

@@ -0,0 +1,27 @@
+import sys
+
+import requests
+
+
+def download(url, download_path, description=""):
+    with open(download_path, "wb") as f:
+        print(f"Downloading {description}...")
+
+        response = requests.get(url, stream=True)
+        total_size = response.headers.get("content-length")
+
+        if total_size is None:
+            f.write(response.content)
+            return
+
+        bytes_written = 0
+        total_size = int(total_size)
+        for chunk in response.iter_content(chunk_size=4096):
+            bytes_written += len(chunk)
+            f.write(chunk)
+
+            progress = int(25 * bytes_written / total_size)
+            sys.stdout.write("\r[%s%s]" % ("=" * progress, " " * (25 - progress)))
+            sys.stdout.flush()
+
+        print("Download complete!")