SatVisMars 0.0.1__py3-none-any.whl

SatVisMars/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

SatVisMars/animate_slider.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from pathlib import Path as FilePath
+from typing import Optional
+
+import matplotlib.animation as animation
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.path import Path
+from matplotlib.patches import PathPatch
+from matplotlib.widgets import Slider
+
+from .calc import Visibility
+
+MARS_MAP_PATH = FilePath(__file__).resolve().parent / "img" / "mars_names.png"
+
+
+class VisibilityWidget:
+    """Animate the Phobos visibility footprint over an equirectangular Mars map."""
+
+    def __init__(
+        self,
+        visibility: Optional[Visibility] = None,
+        image_path: FilePath = MARS_MAP_PATH,
+        footprint_points: int = 500,
+    ):
+        self.visibility = visibility or Visibility()
+        self.image_path = image_path
+        self.footprint_points = footprint_points
+        self._fig = None
+        self._ax = None
+        self._long_slider = None
+        self._shade_patch = None
+        self._boundary_lines: list = []
+
+
+    def _setup_figure(self) -> None:
+        self._fig, self._ax = plt.subplots(figsize=(12, 6))
+
+        # Set up sliders for longitude and latitude
+        self._long_slider_ax = self._fig.add_axes((0.2, 0.01, 0.6, 0.03))
+        self._long_slider = Slider(
+            self._long_slider_ax,
+            "Longitude",
+            valmin=-180,
+            valmax=180,
+            valinit=0,
+            valstep=0.1,
+            orientation="horizontal",
+        )
+
+        # Add slider for radius ratio, see calc.py for more details
+        self._radius_ratio_ax = self._fig.add_axes((0.03, 0.2, 0.03, 0.6))
+        self._radius_ratio_slider = Slider(
+            self._radius_ratio_ax,
+            "Sphere Radius Ratio",
+            valmin=1e-3,
+            valmax=1.0,
+            valinit=self.visibility.radius_ratio,
+            valstep=1e-5,
+            orientation="vertical",
+        )
+        self._radius_ratio_slider.label.set_position((-0.5, 0.5))
+        self._radius_ratio_slider.label.set_rotation(90)
+        self._radius_ratio_slider.label.set_ha("center")
+        self._radius_ratio_slider.label.set_va("center")
+
+        # Add slider for satellite orbit ratio, see calc.py for more details
+        self._satellite_orbit_ratio_ax = self._fig.add_axes((0.92, 0.2, 0.03, 0.6))
+        self._satellite_orbit_ratio_slider = Slider(
+            self._satellite_orbit_ratio_ax,
+            "Satellite Orbit Ratio",
+            valmin=1.0,
+            valmax=50,
+            valinit=self.visibility.satellite_orbit_ratio,
+            valstep=0.1,
+            orientation="vertical",
+        )
+        self._satellite_orbit_ratio_slider.label.set_position((1.5, 0.5))
+        self._satellite_orbit_ratio_slider.label.set_rotation(-90)
+        self._satellite_orbit_ratio_slider.label.set_ha("center")
+        self._satellite_orbit_ratio_slider.label.set_va("center")
+
+        map_image = plt.imread(self.image_path)
+        self._ax.imshow(
+            map_image,
+            extent=(-180.0, 180.0, -90.0, 90.0),
+            origin="upper",
+            aspect="auto",
+        )
+        self._ax.set_xlim(-180, 180)
+        self._ax.set_ylim(-90, 90)
+        self._ax.set_xlabel("Longitude (°)")
+        self._ax.set_ylabel("Latitude (°)")
+        self._ax.set_title("Satellite Visibility Footprint", fontsize=16, pad=12)
+        self._ax.grid(linestyle="--", color="white", alpha=0.35)
+
+        self._shade_patch = PathPatch(
+            Path([[0, 0]]),
+            facecolor="red",
+            alpha=0.1,
+            linewidth=0,
+            edgecolor="none",
+        )
+        self._ax.add_patch(self._shade_patch)
+        (line_east,) = self._ax.plot([], [], color="darkred", linewidth=2)
+        (line_west,) = self._ax.plot([], [], color="darkred", linewidth=2)
+        self._boundary_lines = [line_east, line_west]
+
+    @staticmethod
+    def _world_mask_path(hole_lons: np.ndarray, hole_lats: np.ndarray) -> Path:
+        """Build a world-spanning polygon with the visibility footprint cut out."""
+        outer = np.array(
+            [[-180, -90], [180, -90], [180, 90], [-180, 90], [-180, -90]]
+        )
+        hole = np.column_stack([hole_lons, hole_lats])
+        if not np.allclose(hole[0], hole[-1]):
+            hole = np.vstack([hole, hole[0]])
+
+        vertices = np.vstack([outer, hole])
+        codes = np.concatenate(
+            [
+                [Path.MOVETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.CLOSEPOLY],
+                [Path.MOVETO] + [Path.LINETO] * (len(hole) - 2) + [Path.CLOSEPOLY],
+            ]
+        )
+        return Path(vertices, codes)
+
+    def _update(self, _val: float | None = None) -> None:
+        """Redraw footprint from current slider values."""
+        self.visibility.update_params(
+            self._radius_ratio_slider.val,
+            self._satellite_orbit_ratio_slider.val,
+        )
+        subpoint_lon = self._long_slider.val
+        phi_deg, lon_east, lon_west = self.visibility.footprint_boundaries(
+            subpoint_lon, self.footprint_points
+        )
+        poly_lons, poly_lats = self.visibility.footprint_polygon(
+            subpoint_lon, self.footprint_points
+        )
+
+        self._shade_patch.set_path(self._world_mask_path(poly_lons, poly_lats))
+        self._boundary_lines[0].set_data(lon_east, phi_deg)
+        self._boundary_lines[1].set_data(lon_west, phi_deg)
+        self._fig.canvas.draw_idle()
+
+    def interact(self):
+        self._setup_figure()
+        self._long_slider.on_changed(self._update)
+        self._radius_ratio_slider.on_changed(self._update)
+        self._satellite_orbit_ratio_slider.on_changed(self._update)
+        self._update()
+
+        plt.show()

SatVisMars/calc.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Union
+
+import numpy as np
+
+ArrayLike = Union[float, np.ndarray]
+
+
+class Visibility:
+    """
+    Visibility region of an spherical satellite on the equirectangular projected 
+    sphere host surface using the spherical law of cosines:
+
+        cos(alpha) = cos(theta) * cos(phi - phi0)
+
+    where alpha is the maximum elevation angle (latitude) such that the satellite is visible, 
+    theta is surface latitude, phi is surface longitude, and phi0 is the sub-satellite longitude.
+    Note that this assumes perfect equitorial orbit, where the satellite is always on top of the equator.
+
+    Parameters:
+        radius_ratio (float): Ratio of the satellite radius (r) to Mars surface radius (R)
+        satellite_orbit_ratio (float): Ratio of the satellite orbit radius (d) to R + r
+  """
+    # Mess around with these values to see how the visibility footprint changes
+    def __init__(self, radius_ratio: float = 0.1, satellite_orbit_ratio: float = 2.0):
+        """
+        Parameters:
+            radius_ratio: Ratio of the satellite radius (r) to the host surface radius (R)
+            satellite_orbit_ratio: Ratio of the satellite orbit radius (d) to R + r
+        """
+        self.radius_ratio = radius_ratio
+        self.satellite_orbit_ratio = satellite_orbit_ratio
+        self._recalculate()
+
+    def _recalculate(self) -> None:
+        # Distances in unitless form
+        self.r = 1.0
+        self.R = self.r / self.radius_ratio
+        self.d = self.satellite_orbit_ratio * (self.R + self.r)
+        self.k = (self.R - self.r) / self.d
+        self.theta_max = np.arccos(self.k)
+        self.max_visibility_deg = np.degrees(self.theta_max)
+
+    def update_params(
+        self, radius_ratio: float, satellite_orbit_ratio: float
+    ) -> None:
+        """Recompute geometry when slider values change."""
+        self.radius_ratio = radius_ratio
+        self.satellite_orbit_ratio = satellite_orbit_ratio
+        self._recalculate()
+
+    def _latitude_grid(self, n_points: int = 500) -> np.ndarray:
+        return np.linspace(-self.theta_max, self.theta_max, n_points)
+
+    def longitude_offset(self, latitudes_rad: np.ndarray) -> np.ndarray:
+        """Angular longitude offset from the sub-satellite point at each latitude."""
+        cos_delta = np.clip(self.k / np.cos(latitudes_rad), -1.0, 1.0)
+        return np.arccos(cos_delta)
+
+    def footprint_boundaries(
+        self, subpoint_longitude_deg: float, n_points: int = 500
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Return latitude (deg) and east/west boundary longitudes (deg) for a
+        given Phobos sub-satellite longitude.
+        """
+        phi = self._latitude_grid(n_points)
+        delta_lambda_deg = np.degrees(self.longitude_offset(phi))
+        phi_deg = np.degrees(phi)
+
+        lon_east = subpoint_longitude_deg + delta_lambda_deg
+        lon_west = subpoint_longitude_deg - delta_lambda_deg
+        return phi_deg, lon_east, lon_west
+
+    def footprint_polygon(
+        self, subpoint_longitude_deg: float, n_points: int = 500
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Return a closed polygon (longitudes, latitudes) tracing the footprint."""
+        phi_deg, lon_east, lon_west = self.footprint_boundaries(
+            subpoint_longitude_deg, n_points
+        )
+
+        west_edge_lons = lon_west
+        west_edge_lats = phi_deg
+        east_edge_lons = lon_east[::-1]
+        east_edge_lats = phi_deg[::-1]
+
+        lons = np.concatenate([west_edge_lons, east_edge_lons])
+        lats = np.concatenate([west_edge_lats, east_edge_lats])
+        return lons, lats
+
+    @staticmethod
+    def lon_lat_to_pixel(
+        lon_deg: ArrayLike,
+        lat_deg: ArrayLike,
+        image_width: int = 2048,
+        image_height: int = 1024,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Map geographic coordinates to pixel coordinates on an equirectangular
+        image whose center is (0° latitude, 0° longitude).
+        """
+        lon = np.asarray(lon_deg, dtype=float)
+        lat = np.asarray(lat_deg, dtype=float)
+        x = (lon + 180.0) / 360.0 * image_width
+        y = (90.0 - lat) / 180.0 * image_height
+        return x, y
+
+    @staticmethod
+    def pixel_to_lon_lat(
+        x: ArrayLike,
+        y: ArrayLike,
+        image_width: int = 2048,
+        image_height: int = 1024,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Inverse of lon_lat_to_pixel for equirectangular images."""
+        px = np.asarray(x, dtype=float)
+        py = np.asarray(y, dtype=float)
+        lon = px / image_width * 360.0 - 180.0
+        lat = 90.0 - py / image_height * 180.0
+        return lon, lat

SatVisMars/main.py

@@ -0,0 +1,12 @@
+from .animate_slider import VisibilityWidget
+from .calc import Visibility
+
+
+def main() -> None:
+    visibility = Visibility(radius_ratio=0.1, satellite_orbit_ratio=2.0)
+    widget = VisibilityWidget(visibility=visibility)
+    widget.interact()
+
+
+if __name__ == "__main__":
+    main()

satvismars-0.0.1.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: SatVisMars
+Version: 0.0.1
+Summary: Interactive satellite visibility visualization for Martian moons
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# MartianMoonVis
+An educational tool to visualize the visibility of satellites 🌕 from the surface of Mars.
+
+Mars has two moons--Phobos and Deimos—-but you're not restricted to only the parameters of the exisiting moons, use sliders to play around with different combinations of the distance and size of the satellite. 
+
+![Widget Screenshot](./img/widget.png)
+
+## How to run
+After cloning the repo, run python main.py 
+
+`git clone https://github.com/VismayaRP/MartianEclipses` 
+
+`python main.py`
+
+
+[![A rectangular badge, half black half purple containing the text made at Code Astro](https://img.shields.io/badge/Made%20at-Code/Astro-blueviolet.svg)](https://semaphorep.github.io/codeastro/)
+![Static Badge](https://img.shields.io/badge/license-MIT-blue?link=https%3A%2F%2Fopensource.org%2Flicense%2Fmit)

satvismars-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+SatVisMars/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+SatVisMars/animate_slider.py,sha256=NaroqeWL53z2qv9JpixvrneTqDE8qFL50_U_S_m9h6E,5667
+SatVisMars/calc.py,sha256=4H9tLEaVhLtuKEKpbuwjaoqVv9sg8K7zYE5Hwti05lw,4690
+SatVisMars/main.py,sha256=Dsih5Y_OMci33ba0hPr878g5tlteR2FF5lVnFpq29sI,284
+SatVisMars/img/Phobos.png,sha256=p84XDfrdzjSUW-iz8G7fyBh2lAeXTXx42bUr1yWXkSc,17190381
+SatVisMars/img/mars_coords.png,sha256=vSJ30dNtH1ACVwc0ZwCt9MHpjERz5IEepk1cuXfWWLM,3183701
+SatVisMars/img/mars_name_coord.png,sha256=dwsljDfpYoOdcmsK7JcpWjbz1ekgzE9b8fsUPb1gaZ0,3281236
+SatVisMars/img/mars_names.png,sha256=HtBFGm6ylvwca52dDM6IVHXcQVV6INAhGag3NnDg3OQ,3258873
+SatVisMars/img/mars_nocoord.png,sha256=nom6wX6G-9DEneGd-U1_0o3yjBE89d3S8_v0bQcL5BU,3166823
+satvismars-0.0.1.dist-info/licenses/LICENSE,sha256=pAZXnNE2dxxwXFIduGyn1gpvPefJtUYOYZOi3yeGG94,1068
+satvismars-0.0.1.dist-info/METADATA,sha256=OFoR4XBYke6A-PhDL2ih9g0RbTHWT5NKHUFVy2pTfxU,1094
+satvismars-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+satvismars-0.0.1.dist-info/entry_points.txt,sha256=Ge8XplPhfY7xuJTiGgscpSVSyWTCUtCebeoxTyRv6yM,52
+satvismars-0.0.1.dist-info/top_level.txt,sha256=zLrkJpfJdphJVC8AqhmNK0PfIo4FFTWRqjO4iGU64l4,11
+satvismars-0.0.1.dist-info/RECORD,,

satvismars-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

satvismars-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+SatVisMars = SatVisMars.main:main

satvismars-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

satvismars-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+SatVisMars