gri-plot 0.2.0.post1__py3-none-any.whl

gri_plot/shapes/cone.py

@@ -0,0 +1,227 @@
+"""Cone shape for 3D visualization."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from gri_plot.shapes.meshgen import AXIS_ALIGNMENT_THRESHOLD, cone_mesh
+from gri_plot.surfaces import ImplicitShape
+from gri_plot.surfaces.mesh import vertices_to_mesh3d
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import plotly.graph_objects as go
+    from numpy.typing import NDArray
+
+
+class Cone(ImplicitShape):
+    """A 3D cone defined by apex, axis direction, and half-angle.
+
+    The cone extends from the apex along the axis direction with the
+    specified half-angle.
+
+    Attributes:
+        apex_xyz: Apex (tip) of the cone in XYZ coordinates.
+        axis: Normalized axis direction.
+        half_angle: Half-angle of the cone in radians.
+        height: Height (length along axis) of the cone.
+        label: Optional label for legends.
+        is_volume: Whether this shape represents a volume or surface.
+    """
+
+    def __init__(  # noqa: PLR0913 - 3D cone requires apex + axis + angle + height
+        self,
+        apex_xyz: NDArray[np.floating],
+        axis: NDArray[np.floating],
+        half_angle: float,
+        height: float,
+        label: str | None = None,
+        *,
+        as_volume: bool = True,
+    ) -> None:
+        """Initialize the cone.
+
+        Args:
+            apex_xyz: Apex (tip) of the cone, shape (3,).
+            axis: Axis direction (will be normalized), shape (3,).
+            half_angle: Half-angle of the cone in radians (0 < angle < pi/2).
+            height: Height (length along axis) of the cone (positive).
+            label: Optional label for legends.
+            as_volume: Keyword-only. If True, interior is solution region.
+                If False, boundary is solution locus. Default True.
+
+        Raises:
+            ValueError: If half_angle is not in (0, pi/2) or height is not positive.
+        """
+        self._apex = np.asarray(apex_xyz, dtype=np.float64)
+        axis = np.asarray(axis, dtype=np.float64)
+        self._axis = axis / np.linalg.norm(axis)
+
+        if not 0 < half_angle < np.pi / 2:
+            raise ValueError("half_angle must be in (0, pi/2)")
+        self._half_angle = float(half_angle)
+
+        if height <= 0:
+            raise ValueError("height must be positive")
+        self._height = float(height)
+
+        self._label = label
+        self._is_volume = as_volume
+
+        # Precompute orthonormal basis for residual calculations
+        self._compute_basis()
+
+    def _compute_basis(self) -> None:
+        """Compute orthonormal basis vectors perpendicular to axis."""
+        if abs(self._axis[2]) < AXIS_ALIGNMENT_THRESHOLD:
+            perp1 = np.cross(self._axis, np.array([0.0, 0.0, 1.0]))
+        else:
+            perp1 = np.cross(self._axis, np.array([1.0, 0.0, 0.0]))
+        self._perp1 = perp1 / np.linalg.norm(perp1)
+        self._perp2 = np.cross(self._axis, self._perp1)
+
+    @property
+    def apex_xyz(self) -> NDArray[np.floating]:
+        """Get the apex in XYZ coordinates."""
+        return self._apex
+
+    @property
+    def axis(self) -> NDArray[np.floating]:
+        """Get the normalized axis direction."""
+        return self._axis
+
+    @property
+    def half_angle(self) -> float:
+        """Get the half-angle in radians."""
+        return self._half_angle
+
+    @property
+    def height(self) -> float:
+        """Get the height."""
+        return self._height
+
+    @property
+    def label(self) -> str | None:
+        """Get the label."""
+        return self._label
+
+    @property
+    def is_volume(self) -> bool:
+        """Whether this shape represents a volume (True) or surface (False)."""
+        return self._is_volume
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the residual function for the cone.
+
+        The residual is the angular deviation from the cone surface, so:
+        - 0 on the surface
+        - Positive outside the cone
+        - Negative inside the cone
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        xyz = np.asarray(xyz)
+        diff = xyz - self._apex
+
+        # Distance along axis
+        h = np.einsum("...i,i->...", diff, self._axis)
+
+        # Perpendicular distance
+        h_expanded = np.einsum("...i,i->...", diff, self._axis)[..., np.newaxis]
+        parallel = h_expanded * self._axis
+        perp = diff - parallel
+        r = np.linalg.norm(perp, axis=-1)
+
+        # Expected radius at this height
+        expected_r = h * np.tan(self._half_angle)
+
+        # Residual: difference between actual and expected radius
+        # Normalized by distance from apex to make it scale-independent
+        distance = np.linalg.norm(diff, axis=-1)
+        distance = np.maximum(distance, 1e-10)  # Avoid division by zero
+
+        return (r - expected_r) / distance
+
+    def to_mesh(
+        self,
+        resolution: int | None = None,
+    ) -> tuple[NDArray[np.floating], NDArray[np.integer]]:
+        """Generate mesh vertices and faces.
+
+        Args:
+            resolution: Number of samples per dimension. If None, uses 50.
+
+        Returns:
+            Tuple of (vertices, faces).
+        """
+        if resolution is None:
+            resolution = 50
+        return cone_mesh(
+            self._apex,
+            self._axis,
+            self._half_angle,
+            self._height,
+            resolution,
+        )
+
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Get axis-aligned bounding box in XYZ coordinates.
+
+        Returns:
+            Tuple of (min_corner, max_corner).
+        """
+        # Tip of cone
+        tip = self._apex
+        # Base of cone
+        base_center = self._apex + self._height * self._axis
+        base_radius = self._height * np.tan(self._half_angle)
+
+        # The base circle can extend in any direction perpendicular to axis
+        # Compute the maximum extent by sampling base circle at cardinal directions
+        perps = [self._perp1, -self._perp1, self._perp2, -self._perp2]
+        base_points = [base_center + base_radius * p for p in perps]
+        points = np.array([tip, *base_points])
+        return points.min(axis=0), points.max(axis=0)
+
+    def to_trace(
+        self,
+        resolution: int | None = None,
+        intensity_fn: Callable[[NDArray[np.floating]], NDArray[np.floating]]
+        | None = None,
+        **kwargs,
+    ) -> go.Mesh3d:
+        """Generate a Plotly Mesh3d trace.
+
+        Args:
+            resolution: Mesh resolution.
+            intensity_fn: Optional intensity function for coloring.
+            **kwargs: Additional arguments for vertices_to_mesh3d.
+
+        Returns:
+            Plotly Mesh3d trace.
+        """
+        vertices, faces = self.to_mesh(resolution)
+        return vertices_to_mesh3d(
+            vertices,
+            faces,
+            intensity_fn=intensity_fn,
+            name=self._label,
+            **kwargs,
+        )
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"Cone(apex={self._apex}, axis={self._axis}, "
+            f"half_angle={self._half_angle:.4f}, height={self._height})"
+        )
+
+
+__all__ = ["Cone"]

gri_plot/shapes/cylinder.py

@@ -0,0 +1,219 @@
+"""Cylinder shape for 3D visualization."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from gri_plot.shapes.meshgen import AXIS_ALIGNMENT_THRESHOLD, cylinder_mesh
+from gri_plot.surfaces import ImplicitShape
+from gri_plot.surfaces.mesh import vertices_to_mesh3d
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import plotly.graph_objects as go
+    from numpy.typing import NDArray
+
+
+class Cylinder(ImplicitShape):
+    """A 3D cylinder defined by center, axis, radius, and height.
+
+    The cylinder is centered at the given point and extends height/2
+    in each direction along the axis.
+
+    Attributes:
+        center_xyz: Center of the cylinder in XYZ coordinates.
+        axis: Normalized axis direction.
+        radius: Radius of the cylinder.
+        height: Total height of the cylinder.
+        label: Optional label for legends.
+        is_volume: Whether this shape represents a volume or surface.
+    """
+
+    def __init__(  # noqa: PLR0913 - 3D cylinder requires center + axis + radius + height
+        self,
+        center_xyz: NDArray[np.floating],
+        axis: NDArray[np.floating],
+        radius: float,
+        height: float,
+        label: str | None = None,
+        *,
+        as_volume: bool = True,
+    ) -> None:
+        """Initialize the cylinder.
+
+        Args:
+            center_xyz: Center of the cylinder, shape (3,).
+            axis: Axis direction (will be normalized), shape (3,).
+            radius: Radius of the cylinder (positive).
+            height: Total height of the cylinder (positive).
+            label: Optional label for legends.
+            as_volume: Keyword-only. If True, interior is solution region.
+                If False, boundary is solution locus. Default True.
+
+        Raises:
+            ValueError: If radius or height is not positive.
+        """
+        self._center = np.asarray(center_xyz, dtype=np.float64)
+        axis = np.asarray(axis, dtype=np.float64)
+        self._axis = axis / np.linalg.norm(axis)
+
+        if radius <= 0:
+            raise ValueError("radius must be positive")
+        self._radius = float(radius)
+
+        if height <= 0:
+            raise ValueError("height must be positive")
+        self._height = float(height)
+
+        self._label = label
+        self._is_volume = as_volume
+
+        # Precompute orthonormal basis
+        self._compute_basis()
+
+    def _compute_basis(self) -> None:
+        """Compute orthonormal basis vectors perpendicular to axis."""
+        if abs(self._axis[2]) < AXIS_ALIGNMENT_THRESHOLD:
+            perp1 = np.cross(self._axis, np.array([0.0, 0.0, 1.0]))
+        else:
+            perp1 = np.cross(self._axis, np.array([1.0, 0.0, 0.0]))
+        self._perp1 = perp1 / np.linalg.norm(perp1)
+        self._perp2 = np.cross(self._axis, self._perp1)
+
+    @property
+    def center_xyz(self) -> NDArray[np.floating]:
+        """Get the center in XYZ coordinates."""
+        return self._center
+
+    @property
+    def axis(self) -> NDArray[np.floating]:
+        """Get the normalized axis direction."""
+        return self._axis
+
+    @property
+    def radius(self) -> float:
+        """Get the radius."""
+        return self._radius
+
+    @property
+    def height(self) -> float:
+        """Get the height."""
+        return self._height
+
+    @property
+    def label(self) -> str | None:
+        """Get the label."""
+        return self._label
+
+    @property
+    def is_volume(self) -> bool:
+        """Whether this shape represents a volume (True) or surface (False)."""
+        return self._is_volume
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the residual function for the cylinder.
+
+        The residual is the perpendicular distance from the axis minus
+        the radius, so:
+        - 0 on the surface
+        - Positive outside
+        - Negative inside
+
+        Note: This only considers the cylindrical surface, not the end caps.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        xyz = np.asarray(xyz)
+        diff = xyz - self._center
+
+        # Component along axis
+        parallel = np.einsum("...i,i->...", diff, self._axis)
+
+        # Perpendicular component
+        parallel_vec = parallel[..., np.newaxis] * self._axis
+        perp = diff - parallel_vec
+        perp_dist = np.linalg.norm(perp, axis=-1)
+
+        return perp_dist - self._radius
+
+    def to_mesh(
+        self,
+        resolution: int | None = None,
+    ) -> tuple[NDArray[np.floating], NDArray[np.integer]]:
+        """Generate mesh vertices and faces.
+
+        Args:
+            resolution: Number of samples per dimension. If None, uses 50.
+
+        Returns:
+            Tuple of (vertices, faces).
+        """
+        if resolution is None:
+            resolution = 50
+        return cylinder_mesh(
+            self._center,
+            self._axis,
+            self._radius,
+            self._height,
+            resolution,
+        )
+
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Get axis-aligned bounding box in XYZ coordinates.
+
+        Returns:
+            Tuple of (min_corner, max_corner).
+        """
+        # Endpoints along axis
+        half_h = self._height / 2
+        end1 = self._center - half_h * self._axis
+        end2 = self._center + half_h * self._axis
+
+        # Sample the circles at each end
+        perps = [self._perp1, -self._perp1, self._perp2, -self._perp2]
+        points = [end + self._radius * perp for end in [end1, end2] for perp in perps]
+        points = np.array(points)
+        return points.min(axis=0), points.max(axis=0)
+
+    def to_trace(
+        self,
+        resolution: int | None = None,
+        intensity_fn: Callable[[NDArray[np.floating]], NDArray[np.floating]]
+        | None = None,
+        **kwargs,
+    ) -> go.Mesh3d:
+        """Generate a Plotly Mesh3d trace.
+
+        Args:
+            resolution: Mesh resolution.
+            intensity_fn: Optional intensity function for coloring.
+            **kwargs: Additional arguments for vertices_to_mesh3d.
+
+        Returns:
+            Plotly Mesh3d trace.
+        """
+        vertices, faces = self.to_mesh(resolution)
+        return vertices_to_mesh3d(
+            vertices,
+            faces,
+            intensity_fn=intensity_fn,
+            name=self._label,
+            **kwargs,
+        )
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"Cylinder(center={self._center}, axis={self._axis}, "
+            f"radius={self._radius}, height={self._height})"
+        )
+
+
+__all__ = ["Cylinder"]

gri_plot/shapes/ellipse.py

@@ -0,0 +1,117 @@
+"""2D ellipse shape for error ellipse visualization.
+
+This module provides a standalone 2D ellipse class for rendering geolocation
+error ellipses. Unlike the 3D shapes that inherit from ImplicitShape, this
+is a simple 2D boundary representation parameterized by semi-major axis,
+semi-minor axis, and orientation.
+"""
+
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class Ellipse:
+    """2D ellipse defined by semi-axes and orientation.
+
+    Represents a 2D error ellipse in an East/North coordinate frame,
+    parameterized the same way as gri-ell's Ell.ellipse output:
+    semi-major axis, semi-minor axis, and orientation in degrees
+    clockwise from North.
+
+    Args:
+        sma: Semi-major axis length in meters. Must be positive and >= smi.
+        smi: Semi-minor axis length in meters. Must be positive.
+        ori_deg: Orientation in degrees clockwise from North.
+            Normalized to [0, 360).
+        center: Center point as (east_m, north_m). Defaults to origin.
+        label: Optional label for legend display.
+
+    Raises:
+        ValueError: If axes are non-positive or sma < smi.
+    """
+
+    def __init__(  # noqa: D107
+        self,
+        sma: float,
+        smi: float,
+        ori_deg: float,
+        center: tuple[float, float] = (0.0, 0.0),
+        label: str | None = None,
+    ) -> None:
+        if sma <= 0 or smi <= 0:
+            msg = f"Semi-axes must be positive, got sma={sma}, smi={smi}"
+            raise ValueError(msg)
+        if sma < smi:
+            msg = (
+                f"Semi-major axis must be >= semi-minor axis, got sma={sma}, smi={smi}"
+            )
+            raise ValueError(msg)
+        self._sma = float(sma)
+        self._smi = float(smi)
+        self._ori_deg = float(ori_deg) % 360.0
+        self._center = (float(center[0]), float(center[1]))
+        self._label = label
+
+    @property
+    def sma(self) -> float:
+        """Semi-major axis length in meters."""
+        return self._sma
+
+    @property
+    def smi(self) -> float:
+        """Semi-minor axis length in meters."""
+        return self._smi
+
+    @property
+    def ori_deg(self) -> float:
+        """Orientation in degrees clockwise from North, in [0, 360)."""
+        return self._ori_deg
+
+    @property
+    def center(self) -> tuple[float, float]:
+        """Center point as (east_m, north_m)."""
+        return self._center
+
+    @property
+    def label(self) -> str | None:
+        """Optional label for legend display."""
+        return self._label
+
+    def boundary(self, n_pts: int = 200) -> tuple[NDArray, NDArray]:
+        """Compute ellipse boundary points in East/North meters.
+
+        Args:
+            n_pts: Number of boundary points to generate.
+
+        Returns:
+            Tuple of (east, north) arrays, each of length n_pts.
+        """
+        theta = np.linspace(0, 2 * np.pi, n_pts)
+        # Ellipse in local frame: SMA along x, SMI along y
+        x_local = self._sma * np.cos(theta)
+        y_local = self._smi * np.sin(theta)
+        # Rotate: ori_deg CW from North -> CCW from East = (90 - ori_deg)
+        angle_rad = math.radians(90.0 - self._ori_deg)
+        cos_a = math.cos(angle_rad)
+        sin_a = math.sin(angle_rad)
+        east = cos_a * x_local - sin_a * y_local + self._center[0]
+        north = sin_a * x_local + cos_a * y_local + self._center[1]
+        return east, north
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        parts = [
+            f"Ellipse(sma={self._sma:.1f}",
+            f"smi={self._smi:.1f}",
+            f"ori={self._ori_deg:.1f} deg",
+        ]
+        if self._center != (0.0, 0.0):
+            parts.append(f"center=({self._center[0]:.1f}, {self._center[1]:.1f})")
+        if self._label is not None:
+            parts.append(f"label={self._label!r}")
+        return ", ".join(parts) + ")"