starplot 0.18.1__py2.py3-none-any.whl → 0.19.0__py2.py3-none-any.whl

starplot/plotters/text.py

@@ -0,0 +1,464 @@
+from dataclasses import dataclass
+from random import randrange
+
+import numpy as np
+import rtree
+from shapely import Point
+from matplotlib.text import Text
+
+from starplot.config import settings as StarplotSettings, SvgTextType
+from starplot.styles import AnchorPointEnum, LabelStyle
+from starplot.styles.helpers import use_style
+from starplot.geometry import (
+    unwrap_polygon_360,
+    random_point_in_polygon_at_distance,
+)
+
+"""
+Long term strategy:
+
+- plot all markers FIRST (but keep track of labels)
+- on export, find best positions for labels
+- introduce some "priority" for labels (e.g. order by)
+
+"""
+
+BBox = tuple[float, float, float, float]
+
+
+@dataclass
+class CollisionHandler:
+    """
+    Dataclass that describes how to handle label collisions with other objects, like text, markers, constellation lines, etc.
+    """
+
+    allow_clipped: bool = False
+    """If True, then labels will be plotted if they're clipped (i.e. part of the label is outside the plot area)"""
+
+    allow_label_collisions: bool = False
+    """If True, then labels will be plotted if they collide with another label"""
+
+    allow_marker_collisions: bool = False
+    """If True, then labels will be plotted if they collide with another marker"""
+
+    allow_constellation_line_collisions: bool = False
+    """If True, then labels will be plotted if they collide with a constellation line"""
+
+    plot_on_fail: bool = False
+    """If True, then labels will be plotted even if no allowed position is found. They will be plotted at their last attempted position."""
+
+    attempts: int = 500
+    """Max attempts to find a good label position"""
+
+    seed: int = None
+    """Random seed for randomly generating points"""
+
+    anchor_fallbacks: list[AnchorPointEnum] = None
+    """
+    If a point-based label's preferred anchor point results in a collision, then these fallbacks will be tried in 
+    sequence until a collision-free position is found.
+
+    Default:
+    ```python
+    [
+        AnchorPointEnum.BOTTOM_RIGHT,
+        AnchorPointEnum.TOP_LEFT,
+        AnchorPointEnum.TOP_RIGHT,
+        AnchorPointEnum.BOTTOM_LEFT,
+        AnchorPointEnum.BOTTOM_CENTER,
+        AnchorPointEnum.TOP_CENTER,
+        AnchorPointEnum.RIGHT_CENTER,
+        AnchorPointEnum.LEFT_CENTER,
+    ]
+    ```
+    """
+
+    def __post_init__(self):
+        self.anchor_fallbacks = self.anchor_fallbacks or [
+            AnchorPointEnum.BOTTOM_RIGHT,
+            AnchorPointEnum.TOP_LEFT,
+            AnchorPointEnum.TOP_RIGHT,
+            AnchorPointEnum.BOTTOM_LEFT,
+            AnchorPointEnum.BOTTOM_CENTER,
+            AnchorPointEnum.TOP_CENTER,
+            AnchorPointEnum.RIGHT_CENTER,
+            AnchorPointEnum.LEFT_CENTER,
+        ]
+
+
+class TextPlotterMixin:
+    def __init__(self, *args, **kwargs):
+        self.labels = []
+        self._labels_rtree = rtree.index.Index()
+        self._constellations_rtree = rtree.index.Index()
+        self._stars_rtree = rtree.index.Index()
+        self._markers_rtree = rtree.index.Index()
+        self.collision_handler = kwargs.pop("collision_handler", CollisionHandler())
+
+    def _is_label_collision(self, bbox: BBox) -> bool:
+        ix = list(self._labels_rtree.intersection(bbox))
+        return len(ix) > 0
+
+    def _is_constellation_collision(self, bbox: BBox) -> bool:
+        ix = list(self._constellations_rtree.intersection(bbox))
+        return len(ix) > 0
+
+    def _is_star_collision(self, bbox: BBox) -> bool:
+        ix = list(self._stars_rtree.intersection(bbox))
+        return len(ix) > 0
+
+    def _is_marker_collision(self, bbox: BBox) -> bool:
+        ix = list(self._markers_rtree.intersection(bbox))
+        return len(ix) > 0
+
+    def _is_clipped(self, points) -> bool:
+        p = self._clip_path_polygon
+
+        for x, y in points:
+            if not p.contains(Point(x, y)):
+                return True
+
+        return False
+
+    def _add_label_to_rtree(self, label: Text, extent=None):
+        extent = extent or label.get_window_extent(
+            renderer=self.fig.canvas.get_renderer()
+        )
+        self.labels.append(label)
+        self._labels_rtree.insert(
+            0, (extent.x0 - 1, extent.y0 - 1, extent.x1 + 1, extent.y1 + 1)
+        )
+
+    def _is_open_space(
+        self,
+        bbox: BBox,
+        padding=0,
+        avoid_clipped=True,
+        avoid_label_collisions=True,
+        avoid_marker_collisions=True,
+        avoid_constellation_collision=True,
+    ) -> bool:
+        """
+        Returns true if the boox covers an open space (i.e. no collisions)
+
+        Args:
+            bbox: 4-element tuple of lower left and upper right coordinates
+        """
+        x0, y0, x1, y1 = bbox
+        points = [(x0, y0), (x1, y1)]
+        bbox = (
+            x0 - padding,
+            y0 - padding,
+            x1 + padding,
+            y1 + padding,
+        )
+
+        if any([np.isnan(c) for c in (x0, y0, x1, y1)]):
+            return False
+
+        if avoid_clipped and self._is_clipped(points):
+            return False
+
+        if avoid_label_collisions and self._is_label_collision(bbox):
+            return False
+
+        if avoid_marker_collisions and (
+            self._is_star_collision(bbox) or self._is_marker_collision(bbox)
+        ):
+            return False
+
+        if avoid_constellation_collision and self._is_constellation_collision(bbox):
+            return False
+
+        return True
+
+    def _get_label_bbox(self, label: Text) -> BBox:
+        extent = label.get_window_extent(renderer=self.fig.canvas.get_renderer())
+        return (float(extent.x0), float(extent.y0), float(extent.x1), float(extent.y1))
+
+    def _maybe_remove_label(
+        self,
+        label: Text,
+        collision_handler: CollisionHandler,
+    ) -> bool:
+        """Returns true if the label is removed, else false"""
+        extent = label.get_window_extent(renderer=self.fig.canvas.get_renderer())
+        bbox = (float(extent.x0), float(extent.y0), float(extent.x1), float(extent.y1))
+        points = [(extent.x0, extent.y0), (extent.x1, extent.y1)]
+
+        if any([np.isnan(c) for c in bbox]):
+            label.remove()
+            return True
+
+        if not collision_handler.allow_clipped and self._is_clipped(points):
+            label.remove()
+            return True
+
+        if not collision_handler.allow_label_collisions and self._is_label_collision(
+            bbox
+        ):
+            label.remove()
+            return True
+
+        if not collision_handler.allow_marker_collisions and (
+            self._is_star_collision(bbox) or self._is_marker_collision(bbox)
+        ):
+            label.remove()
+            return True
+
+        if (
+            not collision_handler.allow_constellation_line_collisions
+            and self._is_constellation_collision(bbox)
+        ):
+            label.remove()
+            return True
+
+        return False
+
+    def _text(self, x, y, text, **kwargs) -> Text:
+        """Plots text at (x, y)"""
+        label = self.ax.annotate(
+            text,
+            (x, y),
+            **kwargs,
+            **self._plot_kwargs(),
+        )
+        if kwargs.get("clip_on"):
+            label.set_clip_on(True)
+            label.set_clip_path(self._background_clip_path)
+        return label
+
+    def _text_point(
+        self,
+        ra: float,
+        dec: float,
+        text: str,
+        collision_handler: CollisionHandler,
+        **kwargs,
+    ) -> Text | None:
+        if not text:
+            return None
+
+        x, y = self._prepare_coords(ra, dec)
+
+        if StarplotSettings.svg_text_type == SvgTextType.PATH:
+            kwargs["path_effects"] = kwargs.get("path_effects", [self.text_border])
+
+        original_va = kwargs.pop("va", None)
+        original_ha = kwargs.pop("ha", None)
+        original_offset_x, original_offset_y = kwargs.pop("xytext", (0, 0))
+        attempts = 0
+
+        anchors = [(original_va, original_ha)]
+        for a in collision_handler.anchor_fallbacks:
+            d = AnchorPointEnum.from_str(a).as_matplot()
+            anchors.append((d["va"], d["ha"]))
+
+        for va, ha in anchors:
+            attempts += 1
+            offset_x, offset_y = original_offset_x, original_offset_y
+            if original_ha != ha:
+                offset_x *= -1
+
+            if original_va != va:
+                offset_y *= -1
+
+            if ha == "center":
+                offset_x = 0
+                offset_y = 0
+
+            label = self._text(
+                x, y, text, va=va, ha=ha, xytext=(offset_x, offset_y), **kwargs
+            )
+
+            if (
+                collision_handler.plot_on_fail
+                and label
+                and (attempts == collision_handler.attempts or attempts == len(anchors))
+            ):
+                self._add_label_to_rtree(label)
+                return label
+
+            removed = self._maybe_remove_label(label, collision_handler)
+
+            if not removed:
+                self._add_label_to_rtree(label)
+                return label
+            elif attempts == collision_handler.attempts or attempts == len(anchors):
+                return None
+
+                # from matplotlib.patches import Rectangle
+                # bbox = label.get_window_extent(renderer=self.fig.canvas.get_renderer())
+                # bbox = bbox.transformed(self.ax.transAxes.inverted())
+                # # bbox = bbox.padded(1)
+                # # bbox = bbox.expanded(1, 2)
+                # rect = Rectangle(
+                #     # Bbox(x0=0.19034844035799406, y0=0.8351746595026188, x1=0.20519408725358892, y1=0.8615984521601776)
+                #     (bbox.x0, bbox.y0),  # (x, y) position in display pixels
+                #     width=bbox.width,
+                #     height=bbox.height,
+                #     transform=self.ax.transAxes,
+                #     fill=False,
+                #     facecolor='none',
+                #     edgecolor='red',
+                #     linewidth=1,
+                #     alpha=1,
+                #     zorder=100_000,
+                # )
+                # self.ax.add_patch(rect)
+
+    def _text_area(
+        self,
+        ra: float,
+        dec: float,
+        text: str,
+        area,
+        collision_handler: CollisionHandler,
+        **kwargs,
+    ) -> Text | None:
+        kwargs["va"] = "center"
+        kwargs["ha"] = "center"
+
+        if StarplotSettings.svg_text_type == SvgTextType.PATH:
+            kwargs["path_effects"] = kwargs.get("path_effects", [self.text_border])
+
+        padding = 6
+        max_distance = 3_000
+        distance_step_size = 2
+        attempts = 0
+        height = None
+        width = None
+        bbox = None
+        areas = (
+            [p for p in area.geoms] if "MultiPolygon" == str(area.geom_type) else [area]
+        )
+        new_areas = []
+        origin = Point(ra, dec)
+
+        for a in areas:
+            unwrapped = unwrap_polygon_360(a)
+            # new_buffer = unwrapped.area / 10 * -1 * buffer * self.scale
+            # new_buffer = -1 * buffer * self.scale
+            # new_poly = unwrapped.buffer(new_buffer)
+            new_areas.append(unwrapped)
+
+        for d in range(0, max_distance, distance_step_size):
+            distance = d / 20
+            poly = randrange(len(new_areas))
+            point = random_point_in_polygon_at_distance(
+                new_areas[poly],
+                origin_point=origin,
+                distance=distance,
+                max_iterations=10,
+                seed=collision_handler.seed,
+            )
+
+            if point is None:
+                continue
+
+            x, y = self._prepare_coords(point.x, point.y)
+
+            if height and width:
+                data_xy = self._proj.transform_point(x, y, self._crs)
+                display_x, display_y = self.ax.transData.transform(data_xy)
+                bbox = (
+                    display_x - width / 2,
+                    display_y - height / 2,
+                    display_x + width / 2,
+                    display_y + height / 2,
+                )
+                label = None
+
+            else:
+                label = self._text(x, y, text, **kwargs)
+                bbox = self._get_label_bbox(label)
+                height = bbox[3] - bbox[1]
+                width = bbox[2] - bbox[0]
+
+            is_open = self._is_open_space(
+                bbox,
+                padding=padding,
+                avoid_clipped=not collision_handler.allow_clipped,
+                avoid_constellation_collision=not collision_handler.allow_constellation_line_collisions,
+                avoid_marker_collisions=not collision_handler.allow_marker_collisions,
+                avoid_label_collisions=not collision_handler.allow_label_collisions,
+            )
+
+            # # TODO : remove label if not fully inside area?
+
+            attempts += 1
+
+            if is_open and label is None:
+                label = self._text(x, y, text, **kwargs)
+
+            if is_open or (
+                collision_handler.plot_on_fail
+                and attempts == collision_handler.attempts
+            ):
+                self._add_label_to_rtree(label)
+                return label
+
+            elif label is not None:
+                label.remove()
+
+            elif attempts == collision_handler.attempts:
+                return None
+
+    @use_style(LabelStyle)
+    def text(
+        self,
+        text: str,
+        ra: float,
+        dec: float,
+        style: LabelStyle = None,
+        collision_handler: CollisionHandler = None,
+        **kwargs,
+    ):
+        """
+        Plots text
+
+        Args:
+            text: Text to plot
+            ra: Right ascension of text (0...360)
+            dec: Declination of text (-90...90)
+            style: Styling of the text
+            collision_handler: An instance of [CollisionHandler][starplot.CollisionHandler] that describes what to do on collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.
+        """
+        if not text:
+            return
+
+        style = style.model_copy()  # need a copy because we possibly mutate it below
+
+        collision_handler = collision_handler or self.collision_handler
+
+        if style.offset_x == "auto":
+            style.offset_x = 0
+
+        if style.offset_y == "auto":
+            style.offset_y = 0
+
+        if kwargs.get("area"):
+            return self._text_area(
+                ra,
+                dec,
+                text,
+                **style.matplot_kwargs(self.scale),
+                area=kwargs.pop("area"),
+                collision_handler=collision_handler,
+                xycoords="data",
+                xytext=(style.offset_x * self.scale, style.offset_y * self.scale),
+                textcoords="offset points",
+                **kwargs,
+            )
+        else:
+            return self._text_point(
+                ra,
+                dec,
+                text,
+                **style.matplot_kwargs(self.scale),
+                collision_handler=collision_handler,
+                xycoords="data",
+                xytext=(style.offset_x * self.scale, style.offset_y * self.scale),
+                textcoords="offset points",
+                **kwargs,
+            )

starplot/styles/__init__.py

@@ -1,6 +1,6 @@
-from .base import *  # noqa: F401,F403
-from .helpers import *  # noqa: F401,F403
+# ruff: noqa: F401,F403
 
-# from .extensions import *  # noqa: F401
+from .base import *
+from .helpers import *
 
-import starplot.styles.extensions as style_extensions  # noqa: F401
+import starplot.styles.extensions as style_extensions

starplot/styles/base.py

@@ -2,7 +2,7 @@ import json
 
 from enum import Enum
 from pathlib import Path
-from typing import Optional, Union, List
+from typing import Optional, Union
 
 import yaml
 
@@ -90,7 +90,7 @@ class FontWeightEnum(int, Enum):
 
     THIN = 100
     EXTRA_LIGHT = 200
-    LIGHT = 300
+    # LIGHT = 300   # matplotlib's font dict doesn't have 300?
     NORMAL = 400
     MEDIUM = 500
     SEMI_BOLD = 600
@@ -98,6 +98,20 @@ class FontWeightEnum(int, Enum):
     EXTRA_BOLD = 800
     HEAVY = 900
 
+    def as_matplot(self) -> str:
+        """Returns the font weight as a matplotlib string, which avoids a bug with integer font weights and rendering text as elements in SVG."""
+        return {
+            FontWeightEnum.THIN: "ultralight",
+            FontWeightEnum.EXTRA_LIGHT: "light",  # matplotlib maps 'light' to 200, which is really extra light
+            # FontWeightEnum.LIGHT: "light",
+            FontWeightEnum.NORMAL: "normal",
+            FontWeightEnum.MEDIUM: "medium",
+            FontWeightEnum.SEMI_BOLD: "semibold",
+            FontWeightEnum.BOLD: "bold",
+            FontWeightEnum.EXTRA_BOLD: "extra bold",
+            FontWeightEnum.HEAVY: "black",
+        }[self.value]
+
 
 class FontStyleEnum(str, Enum):
     NORMAL = "normal"
@@ -598,7 +612,7 @@ class LabelStyle(BaseStyle):
             fontsize=self.font_size * scale,
             fontstyle=self.font_style,
             fontname=self.font_name,
-            weight=self.font_weight,
+            weight=FontWeightEnum(self.font_weight).as_matplot(),
             alpha=self.font_alpha,
             zorder=self.zorder,
         )
@@ -744,7 +758,7 @@ class LegendStyle(BaseStyle):
             framealpha=self.background_alpha,
             prop={
                 "family": self.font_name,
-                "weight": self.font_weight,
+                "weight": FontWeightEnum(self.font_weight),
                 "size": self.font_size * scale,
             },
             labelcolor=self.font_color.as_hex(),
@@ -799,18 +813,6 @@ class PlotStyle(BaseStyle):
 
     text_border_color: ColorStr = ColorStr("#fff")
 
-    text_anchor_fallbacks: List[AnchorPointEnum] = [
-        AnchorPointEnum.BOTTOM_RIGHT,
-        AnchorPointEnum.TOP_LEFT,
-        AnchorPointEnum.TOP_RIGHT,
-        AnchorPointEnum.BOTTOM_LEFT,
-        AnchorPointEnum.BOTTOM_CENTER,
-        AnchorPointEnum.TOP_CENTER,
-        AnchorPointEnum.RIGHT_CENTER,
-        AnchorPointEnum.LEFT_CENTER,
-    ]
-    """If a label's preferred anchor point results in a collision, then these fallbacks will be tried in sequence until a collision-free position is found."""
-
     # Borders
     border_font_size: int = 18
     border_font_weight: FontWeightEnum = FontWeightEnum.BOLD
@@ -858,7 +860,7 @@ class PlotStyle(BaseStyle):
 
     bayer_labels: LabelStyle = LabelStyle(
         font_size=21,
-        font_weight=FontWeightEnum.LIGHT,
+        font_weight=FontWeightEnum.EXTRA_LIGHT,
         font_name="GFS Didot",
         zorder=ZOrderEnum.LAYER_4,
         anchor_point=AnchorPointEnum.TOP_LEFT,
@@ -1158,7 +1160,7 @@ class PlotStyle(BaseStyle):
         label=LabelStyle(
             font_size=22,
             font_color="#999",
-            font_weight=FontWeightEnum.LIGHT,
+            font_weight=FontWeightEnum.EXTRA_LIGHT,
             font_alpha=0.65,
             zorder=ZOrderEnum.LAYER_3,
         ),

starplot/styles/ext/antique.yml

@@ -52,7 +52,7 @@ constellation_lines:
   alpha: 0.3
   color: hsl(48, 80%, 14%)
 constellation_labels:
-  font_weight: 300
+  font_weight: 200
   font_color: hsl(60, 3%, 52%)
   font_alpha: 0.46
   font_name: "serif"
@@ -77,7 +77,7 @@ gridlines:
     font_alpha: 0.8
     font_color: hsl(60, 3%, 92%)
     font_size: 8
-    font_weight: 300
+    font_weight: 200
   line:
     alpha: 0.6
     color: hsl(68, 11%, 71%)

starplot/styles/ext/blue_dark.yml

@@ -45,7 +45,6 @@ constellation_lines:
 constellation_labels:
   font_alpha: 0.37
   font_color: hsl(209, 23%, 80%)
-  font_weight: 300
 constellation_borders:
   width: 2
   color: hsl(209, 50%, 74%)

starplot/styles/ext/color_print.yml

@@ -24,7 +24,7 @@ celestial_equator:
 constellation:
   label:
     font_size: 4
-    font_weight: 300
+    font_weight: 200
     font_color: '#8c8c8c'
     font_alpha: 0.1
   line:
@@ -51,7 +51,7 @@ gridlines:
     font_alpha: 1
     font_color:  hsl(211, 80%, 97%)
     font_size: 18
-    font_weight: 300
+    font_weight: 200
   line:
     alpha: 0.4
     color: '#888'

{starplot-0.18.1.dist-info → starplot-0.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starplot
-Version: 0.18.1
+Version: 0.19.0
 Summary: Star charts and maps of the sky
 Keywords: astronomy,stars,charts,maps,constellations,sky,plotting
 Author-email: Steve Berardi <hello@steveberardi.com>
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Matplotlib
 License-File: LICENSE
 Requires-Dist: matplotlib >= 3.8.0
 Requires-Dist: numpy >= 1.26.2
@@ -39,7 +40,7 @@ Project-URL: Source, https://github.com/steveberardi/starplot
 ![License](https://img.shields.io/github/license/steveberardi/starplot?style=for-the-badge&color=8b63b0)
 ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/steveberardi/starplot/test.yml?style=for-the-badge&color=88b063)
 
-**Starplot** is a Python library for creating star charts and maps of the sky.
+**Starplot** is a Python library for creating star charts and maps of the sky
 
 - 🗺️ **Maps** - including 10+ customizable projections
 - ⭐ **Zenith Charts** - shows the entire sky at a specific time and place
@@ -52,7 +53,7 @@ Project-URL: Source, https://github.com/steveberardi/starplot
 - 🚀 **Data Backend** - powered by DuckDB + Ibis for fast object lookup
 - 📓 **Custom Data Catalogs** - with helpers for building and optimizing
 - 🧭 **Label Collision Avoidance** - ensuring all labels are readable
-- 🌐 **Localization** - label translations for French, Chinese, and Persian (coming soon!)
+- 🌐 **Localization** - label translations for Chinese, French, Lithuanian, Persian, and Spanish
 
 ## Examples
 *Zenith chart of the stars from a specific time/location:*
@@ -135,6 +136,7 @@ See more details on the [Public Roadmap](https://trello.com/b/sUksygn4/starplot-
 - [starplot-hyg](https://github.com/steveberardi/starplot-hyg)
 - [starplot-gaia-dr3](https://github.com/steveberardi/starplot-gaia-dr3)
 - [starplot-hyperleda](https://github.com/steveberardi/starplot-hyperleda)
+- [starplot-milkyway](https://github.com/steveberardi/starplot-milkyway)
 
 ## License
 [MIT License](https://github.com/steveberardi/starplot/blob/main/LICENSE)