stargazing-core 0.1.0__tar.gz

stargazing_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StarGazer1995
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stargazing_core-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: stargazing-core
+Version: 0.1.0
+Summary: Shared astronomical computation for stargazing tools — telescope optics, deep-sky catalog, equipment presets
+Author: StarGazer1995
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy<8.0,>=7.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pytz
+Dynamic: license-file
+
+# stargazing-core
+
+Shared astronomical computation package for the stargazing toolchain —
+telescope optics, deep-sky catalog, and equipment presets used by both
+[mcp-stargazing](https://github.com/StarGazer1995/mcp-stargazing) and
+[stargazing-place-finder](https://github.com/StarGazer1995/stargazing-place-finder).
+
+## Installation
+
+```bash
+pip install stargazing-core
+```
+
+## Quick Start
+
+```python
+from stargazing_core import TelescopeConfig, TelescopeOptics, TELESCOPE_PRESETS
+
+# Look up a preset
+config = TELESCOPE_PRESETS['seestar-s50']
+
+# Compute derived optics
+optics = config.compute_optics()
+print(f'FOV: {optics.fov_width_deg:.1f}° × {optics.fov_height_deg:.1f}°')
+# → FOV: 1.7° × 1.3°
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v
+uv run ruff format --check . && uv run ruff check .
+```

stargazing_core-0.1.0/README.md

@@ -0,0 +1,34 @@
+# stargazing-core
+
+Shared astronomical computation package for the stargazing toolchain —
+telescope optics, deep-sky catalog, and equipment presets used by both
+[mcp-stargazing](https://github.com/StarGazer1995/mcp-stargazing) and
+[stargazing-place-finder](https://github.com/StarGazer1995/stargazing-place-finder).
+
+## Installation
+
+```bash
+pip install stargazing-core
+```
+
+## Quick Start
+
+```python
+from stargazing_core import TelescopeConfig, TelescopeOptics, TELESCOPE_PRESETS
+
+# Look up a preset
+config = TELESCOPE_PRESETS['seestar-s50']
+
+# Compute derived optics
+optics = config.compute_optics()
+print(f'FOV: {optics.fov_width_deg:.1f}° × {optics.fov_height_deg:.1f}°')
+# → FOV: 1.7° × 1.3°
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v
+uv run ruff format --check . && uv run ruff check .
+```

stargazing_core-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stargazing-core"
+version = "0.1.0"
+description = "Shared astronomical computation for stargazing tools — telescope optics, deep-sky catalog, equipment presets"
+requires-python = ">=3.11"
+authors = [
+    { name = "StarGazer1995" },
+]
+readme = "README.md"
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+
+dependencies = [
+    "astropy>=7.0,<8.0",
+    "numpy>=1.24",
+    "pandas>=3.0.3",
+    "pydantic>=2.0",
+    "pytz",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.5",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["stargazing_core*"]
+
+[tool.setuptools.package-data]
+"stargazing_core" = ["data/*.json"]
+
+# ── Ruff ──────────────────────────────
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I",      # pyflakes + isort
+    "N",                       # pep8-naming
+    "B",                       # flake8-bugbear
+    "SIM",                     # flake8-simplify
+    "C4",                      # flake8-comprehensions
+]
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+
+[tool.ruff.lint.isort]
+known-first-party = ["stargazing_core"]
+
+# ── pytest ─────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v --tb=short"

stargazing_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stargazing_core-0.1.0/src/stargazing_core/__init__.py

@@ -0,0 +1,70 @@
+"""stargazing-core — shared astronomical computation.
+
+Provides :class:`TelescopeConfig`, :class:`TelescopeOptics`, equipment presets,
+and deep-sky catalog loading used by both ``mcp-stargazing`` and
+``stargazing-place-finder``.
+"""
+
+from stargazing_core._catalog import DeepSkyCatalog, load_objects
+from stargazing_core._celestial_models import (
+    CelestialPosition,
+    MoonInfo,
+    RiseSet,
+    VisiblePlanet,
+)
+from stargazing_core._constellation import identify_constellation
+from stargazing_core._coord import validate_coordinates
+from stargazing_core._filtering import (
+    filter_candidates_by_lst,
+    match_telescope_targets,
+    score_deep_sky_objects,
+)
+from stargazing_core._geo import GeoBounds, GeoPoint, TimeInfo
+from stargazing_core._moon import calculate_moon_info, get_moon_altaz
+from stargazing_core._mosaic import MosaicGrid, MosaicPanel, compute_mosaic_grid
+from stargazing_core._pagination import PaginatedResult
+from stargazing_core._planets import get_visible_planets
+from stargazing_core._shooting_plan import (
+    ShootingPlan,
+    ShootingSlot,
+    generate_shooting_schedule,
+)
+from stargazing_core._telescope import (
+    TELESCOPE_PRESETS,
+    TelescopeConfig,
+    TelescopeOptics,
+)
+from stargazing_core._timegrid import find_rise_set_indices, generate_time_grid
+
+__all__ = [
+    'TelescopeConfig',
+    'TelescopeOptics',
+    'TELESCOPE_PRESETS',
+    'DeepSkyCatalog',
+    'load_objects',
+    'GeoPoint',
+    'GeoBounds',
+    'TimeInfo',
+    'CelestialPosition',
+    'RiseSet',
+    'MoonInfo',
+    'VisiblePlanet',
+    'PaginatedResult',
+    'validate_coordinates',
+    'calculate_moon_info',
+    'get_moon_altaz',
+    'get_visible_planets',
+    'filter_candidates_by_lst',
+    'match_telescope_targets',
+    'score_deep_sky_objects',
+    'identify_constellation',
+    'generate_time_grid',
+    'find_rise_set_indices',
+    'ShootingPlan',
+    'ShootingSlot',
+    'generate_shooting_schedule',
+    'MosaicPanel',
+    'MosaicGrid',
+    'compute_mosaic_grid',
+]
+__version__ = '0.1.0a1'

stargazing_core-0.1.0/src/stargazing_core/_catalog.py

@@ -0,0 +1,128 @@
+"""Deep-sky object catalog loader.
+
+Reads the embedded ``objects.json`` (11 000+ Messier / NGC / IC objects with
+angular-size data) via :mod:`importlib.resources`.  Callers get plain Python
+``list[dict]`` — no astropy required.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from importlib import resources
+from typing import Any, Optional
+
+# ── Fallback angular sizes by object type ──────────────────────
+# Same values as used by the mcp-stargazing download_data.py script.
+
+_FALLBACK_SIZES: dict[str, tuple[float, float]] = {
+    # galaxies (elongated — min ≈ 0.5 × maj)
+    'Gx': (2.0, 1.0),
+    'GiG': (2.0, 1.0),
+    'GiP': (2.0, 1.0),
+    'GiC': (1.5, 0.7),
+    'SyG': (1.5, 0.7),
+    'Sy1': (1.5, 0.7),
+    'Sy2': (1.5, 0.7),
+    'LIN': (1.5, 0.7),
+    'AGN': (1.5, 0.7),
+    'BLL': (1.5, 0.7),
+    'SBG': (1.5, 0.7),
+    'H2G': (1.5, 0.7),
+    'PaG': (1.5, 0.7),
+    'G': (2.0, 1.0),
+    'AG?': (1.5, 0.7),
+    'IG': (2.0, 1.0),
+    'rG': (1.5, 1.0),
+    'EmG': (2.0, 1.0),
+    'BiC': (2.0, 1.0),
+    'G?': (2.0, 1.0),
+    'PoG': (1.0, 1.0),
+    'mul': (2.0, 2.0),
+    # clusters (round)
+    'GlC': (5.0, 5.0),
+    'Gb': (4.0, 4.0),
+    'OpC': (15.0, 15.0),
+    'Cl*': (10.0, 10.0),
+    'Cl?': (10.0, 10.0),
+    'ClG': (10.0, 10.0),
+    'OC': (10.0, 10.0),
+    # nebulae
+    'PN': (0.5, 0.5),
+    'HII': (15.0, 10.0),
+    'RNe': (15.0, 10.0),
+    'Nb': (15.0, 10.0),
+    'C+N': (15.0, 10.0),
+    'ISM': (20.0, 12.0),
+    'sh': (15.0, 10.0),
+    'Em*': (5.0, 5.0),
+    'GNe': (15.0, 10.0),
+    'EmO': (10.0, 10.0),
+    'HH': (0.5, 0.5),
+    'Opt': (1.0, 1.0),
+    # supernova remnants
+    'SNR': (8.0, 8.0),
+}
+
+# thread-safe cache
+_catalog_cache: Optional[list[dict[str, Any]]] = None
+_catalog_lock = threading.Lock()
+
+
+def _load_data_resource(filename: str) -> list[dict[str, Any]]:
+    """Read packaged JSON data from ``stargazing_core/data/``."""
+    pkg = resources.files('stargazing_core')
+    return json.loads((pkg / 'data' / filename).read_text(encoding='utf-8'))
+
+
+def load_objects() -> list[dict[str, Any]]:
+    """Return the full deep-sky object catalog (thread-safe, cached)."""
+    global _catalog_cache
+
+    if _catalog_cache is not None:
+        return _catalog_cache
+
+    with _catalog_lock:
+        if _catalog_cache is not None:  # pragma: no cover — thread-safety
+            return _catalog_cache
+        _catalog_cache = _load_data_resource('objects.json')
+
+    return _catalog_cache
+
+
+def get_angular_size_fallback(obj_type: str) -> Optional[tuple[float, float]]:
+    """Return ``(maj_arcmin, min_arcmin)`` fallback for *obj_type*, or ``None``."""
+    return _FALLBACK_SIZES.get(obj_type)
+
+
+class DeepSkyCatalog:
+    """Lightweight wrapper around the deep-sky object catalog.
+
+    Loads the 11 000+ object catalog from packaged JSON data on first use.
+    """
+
+    def __init__(self) -> None:
+        self._objects = load_objects()
+
+    def __len__(self) -> int:
+        return len(self._objects)
+
+    def all(self) -> list[dict[str, Any]]:
+        """Return every object in the catalog."""
+        return self._objects
+
+    def by_types(self, types: set[str]) -> list[dict[str, Any]]:
+        """Filter objects whose ``type`` field is in *types*."""
+        return [o for o in self._objects if o.get('type') in types]
+
+    def with_angular_size(self) -> list[dict[str, Any]]:
+        """Return objects that have measured (non-fallback) angular-size data."""
+        return [o for o in self._objects if o.get('angular_size_maj_arcmin') is not None]
+
+    def type_counts(self) -> dict[str, int]:
+        """Return ``{type: count}`` for the full catalog."""
+        counts: dict[str, int] = {}
+        for o in self._objects:
+            t = o.get('type', '?')
+            counts[t] = counts.get(t, 0) + 1
+        return counts

stargazing_core-0.1.0/src/stargazing_core/_celestial_models.py

@@ -0,0 +1,53 @@
+"""Pydantic models for celestial (astronomy) domain data.
+
+These models provide typed representations for values computed by the
+astronomical functions in this package (``calculate_moon_info``,
+``get_visible_planets``, etc.).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class CelestialPosition(BaseModel):
+    """Altitude and azimuth of a celestial object."""
+
+    altitude: float = Field(
+        description='Altitude above horizon in degrees (0°=horizon, 90°=zenith)'
+    )
+    azimuth: float = Field(description='Compass direction in degrees (0°=North, 90°=East)')
+
+
+class RiseSet(BaseModel):
+    """Rise and set times of a celestial object."""
+
+    rise_time: str | None = Field(
+        default=None, description='Rise time as ISO string (local timezone)'
+    )
+    set_time: str | None = Field(
+        default=None, description='Set time as ISO string (local timezone)'
+    )
+
+
+class MoonInfo(BaseModel):
+    """Detailed information about the Moon's phase and position."""
+
+    illumination: float = Field(description='Fraction of the moon illuminated (0.0 to 1.0)')
+    phase_name: str = Field(description="Phase description (e.g. 'Waxing Gibbous')")
+    age_days: float = Field(description='Approximate age of the moon in days since New Moon')
+    elongation: float = Field(description='Angular separation from Sun in degrees')
+    earth_distance: float = Field(description='Distance from Earth in km')
+    altitude: float | None = Field(
+        default=None, description='Altitude above horizon in degrees (requires lat/lon)'
+    )
+    azimuth: float | None = Field(
+        default=None, description='Compass direction in degrees (requires lat/lon)'
+    )
+
+
+class VisiblePlanet(CelestialPosition):
+    """A planet currently visible above the horizon."""
+
+    name: str = Field(description='Planet name')
+    constellation: str | None = Field(default=None, description='Constellation the planet is in')

stargazing_core-0.1.0/src/stargazing_core/_constellation.py

@@ -0,0 +1,14 @@
+"""Constellation identification.
+
+Copied from ``mcp-stargazing/src/celestial.py``.  Pure computation — uses
+astropy's built-in constellation boundaries.
+"""
+
+from astropy.coordinates import SkyCoord, get_constellation
+
+from . import _ephemeris  # noqa: F401 — ensure ephemeris is configured
+
+
+def identify_constellation(sky_coord: SkyCoord) -> str:
+    """Identify which constellation a coordinate belongs to."""
+    return get_constellation(sky_coord)

stargazing_core-0.1.0/src/stargazing_core/_coord.py

@@ -0,0 +1,16 @@
+"""Pure coordinate utilities — no astropy or other heavy deps required.
+
+Originally from ``mcp-stargazing/src/utils.py``.  Kept dependency-free so
+both projects can use these without pulling in astropy.
+"""
+
+
+def validate_coordinates(lat: float, lon: float) -> bool:
+    """Return ``True`` when *lat* and *lon* are within valid geographic ranges.
+
+    >>> validate_coordinates(40.0, 116.0)
+    True
+    >>> validate_coordinates(100.0, 0.0)
+    False
+    """
+    return -90.0 <= lat <= 90.0 and -180.0 <= lon <= 180.0

stargazing_core-0.1.0/src/stargazing_core/_ephemeris.py

@@ -0,0 +1,10 @@
+"""One-time astropy ephemeris configuration.
+
+Importing this module sets the solar-system ephemeris to ``'builtin'`` so
+that planet and moon calculations work without network access.  Must be
+imported before any other astropy coordinate transformations.
+"""
+
+from astropy.coordinates import solar_system_ephemeris
+
+solar_system_ephemeris.set('builtin')