coordinate-system 4.0.3__cp313-cp313-win_amd64.whl → 5.2.0__cp313-cp313-win_amd64.whl

coordinate_system/visualization.py

@@ -0,0 +1,666 @@
+"""
+3D Coordinate System and Curve Visualization Module
+===================================================
+
+This module provides tools for visualizing coordinate systems and curves in 3D space.
+
+Features:
+- Draw coordinate systems with RGB colors (X=Red, Y=Green, Z=Blue)
+- Visualize curves with vertices, tangents, and normals
+- Display coordinate frame fields along curves
+- Support for both single frames and frame arrays
+
+Author: PanGuoJun
+Date: 2025-12-01
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d import Axes3D
+from typing import List, Optional, Tuple, Callable, Union
+
+# Import from the C extension module
+try:
+    from .coordinate_system import vec3, coord3
+except ImportError:
+    # Fallback for development
+    import coordinate_system
+    vec3 = coordinate_system.vec3
+    coord3 = coordinate_system.coord3
+
+
+class CoordinateSystemVisualizer:
+    """
+    三维坐标系可视化工具
+
+    绘制坐标系时使用RGB颜色方案:
+    - X轴: 红色 (Red)
+    - Y轴: 绿色 (Green)
+    - Z轴: 蓝色 (Blue)
+    """
+
+    def __init__(self, figsize: Tuple[int, int] = (12, 9)):
+        """
+        初始化可视化工具
+
+        Args:
+            figsize: 图形大小 (width, height)
+        """
+        self.fig = plt.figure(figsize=figsize)
+        self.ax = self.fig.add_subplot(111, projection='3d')
+        self._setup_axis()
+
+    def _setup_axis(self):
+        """设置坐标轴样式"""
+        self.ax.set_xlabel('X', fontsize=12, color='red')
+        self.ax.set_ylabel('Y', fontsize=12, color='green')
+        self.ax.set_zlabel('Z', fontsize=12, color='blue')
+        self.ax.grid(True, alpha=0.3)
+
+    def draw_coord_system(
+        self,
+        coord: coord3,
+        scale: float = 1.0,
+        linewidth: float = 2.0,
+        alpha: float = 0.8,
+        label_prefix: str = ""
+    ):
+        """
+        绘制单个坐标系
+
+        Args:
+            coord: coord3对象
+            scale: 轴长度缩放因子
+            linewidth: 线宽
+            alpha: 透明度
+            label_prefix: 标签前缀
+        """
+        origin = coord.o
+
+        # X轴 (红色)
+        x_end = origin + coord.ux * scale
+        self.ax.plot(
+            [origin.x, x_end.x],
+            [origin.y, x_end.y],
+            [origin.z, x_end.z],
+            'r-', linewidth=linewidth, alpha=alpha,
+            label=f'{label_prefix}X' if label_prefix else None
+        )
+
+        # Y轴 (绿色)
+        y_end = origin + coord.uy * scale
+        self.ax.plot(
+            [origin.x, y_end.x],
+            [origin.y, y_end.y],
+            [origin.z, y_end.z],
+            'g-', linewidth=linewidth, alpha=alpha,
+            label=f'{label_prefix}Y' if label_prefix else None
+        )
+
+        # Z轴 (蓝色)
+        z_end = origin + coord.uz * scale
+        self.ax.plot(
+            [origin.x, z_end.x],
+            [origin.y, z_end.y],
+            [origin.z, z_end.z],
+            'b-', linewidth=linewidth, alpha=alpha,
+            label=f'{label_prefix}Z' if label_prefix else None
+        )
+
+    def draw_world_coord(
+        self,
+        origin: vec3 = None,
+        scale: float = 1.0,
+        linewidth: float = 3.0
+    ):
+        """
+        绘制世界坐标系
+
+        Args:
+            origin: 原点位置,默认为(0,0,0)
+            scale: 轴长度
+            linewidth: 线宽
+        """
+        if origin is None:
+            origin = vec3(0, 0, 0)
+
+        world_coord = coord3()
+        world_coord.o = origin
+
+        self.draw_coord_system(
+            world_coord,
+            scale=scale,
+            linewidth=linewidth,
+            alpha=1.0,
+            label_prefix="World-"
+        )
+
+    def set_equal_aspect(self):
+        """设置等比例显示"""
+        # 获取当前所有数据的范围
+        xlim = self.ax.get_xlim3d()
+        ylim = self.ax.get_ylim3d()
+        zlim = self.ax.get_zlim3d()
+
+        # 计算范围
+        x_range = abs(xlim[1] - xlim[0])
+        y_range = abs(ylim[1] - ylim[0])
+        z_range = abs(zlim[1] - zlim[0])
+
+        # 使用最大范围
+        max_range = max(x_range, y_range, z_range)
+
+        # 计算中心点
+        x_middle = np.mean(xlim)
+        y_middle = np.mean(ylim)
+        z_middle = np.mean(zlim)
+
+        # 设置相等的范围
+        self.ax.set_xlim3d([x_middle - max_range/2, x_middle + max_range/2])
+        self.ax.set_ylim3d([y_middle - max_range/2, y_middle + max_range/2])
+        self.ax.set_zlim3d([z_middle - max_range/2, z_middle + max_range/2])
+
+    def show(self):
+        """显示图形"""
+        self.ax.legend()
+        plt.tight_layout()
+        plt.show()
+
+    def save(self, filename: str, dpi: int = 300):
+        """
+        保存图形
+
+        Args:
+            filename: 文件名
+            dpi: 分辨率
+        """
+        self.ax.legend()
+        plt.tight_layout()
+        plt.savefig(filename, dpi=dpi, bbox_inches='tight')
+
+
+class CurveVisualizer(CoordinateSystemVisualizer):
+    """
+    曲线可视化工具
+
+    支持绘制:
+    - 曲线顶点
+    - 切线
+    - 法线
+    - 完整坐标系场
+    """
+
+    def __init__(self, figsize: Tuple[int, int] = (12, 9)):
+        """
+        初始化曲线可视化工具
+
+        Args:
+            figsize: 图形大小
+        """
+        super().__init__(figsize)
+
+    def draw_curve_vertices(
+        self,
+        points: List[vec3],
+        color: str = 'black',
+        linewidth: float = 2.0,
+        marker: str = 'o',
+        markersize: float = 4,
+        alpha: float = 0.7,
+        label: str = "Curve"
+    ):
+        """
+        绘制曲线顶点
+
+        Args:
+            points: 顶点列表
+            color: 颜色
+            linewidth: 线宽
+            marker: 标记样式
+            markersize: 标记大小
+            alpha: 透明度
+            label: 标签
+        """
+        if not points:
+            return
+
+        x = [p.x for p in points]
+        y = [p.y for p in points]
+        z = [p.z for p in points]
+
+        self.ax.plot(
+            x, y, z,
+            color=color,
+            linewidth=linewidth,
+            marker=marker,
+            markersize=markersize,
+            alpha=alpha,
+            label=label
+        )
+
+    def draw_tangents(
+        self,
+        points: List[vec3],
+        tangents: List[vec3],
+        scale: float = 0.5,
+        color: str = 'orange',
+        linewidth: float = 1.5,
+        alpha: float = 0.8,
+        arrow: bool = True
+    ):
+        """
+        绘制切线
+
+        Args:
+            points: 曲线点列表
+            tangents: 切线向量列表
+            scale: 切线长度缩放
+            color: 颜色
+            linewidth: 线宽
+            alpha: 透明度
+            arrow: 是否使用箭头
+        """
+        if len(points) != len(tangents):
+            raise ValueError("Points and tangents must have the same length")
+
+        for point, tangent in zip(points, tangents):
+            end = point + tangent * scale
+
+            if arrow:
+                self.ax.quiver(
+                    point.x, point.y, point.z,
+                    tangent.x * scale, tangent.y * scale, tangent.z * scale,
+                    color=color,
+                    linewidth=linewidth,
+                    alpha=alpha,
+                    arrow_length_ratio=0.3
+                )
+            else:
+                self.ax.plot(
+                    [point.x, end.x],
+                    [point.y, end.y],
+                    [point.z, end.z],
+                    color=color,
+                    linewidth=linewidth,
+                    alpha=alpha
+                )
+
+    def draw_normals(
+        self,
+        points: List[vec3],
+        normals: List[vec3],
+        scale: float = 0.5,
+        color: str = 'purple',
+        linewidth: float = 1.5,
+        alpha: float = 0.8,
+        arrow: bool = True
+    ):
+        """
+        绘制法线
+
+        Args:
+            points: 曲线点列表
+            normals: 法线向量列表
+            scale: 法线长度缩放
+            color: 颜色
+            linewidth: 线宽
+            alpha: 透明度
+            arrow: 是否使用箭头
+        """
+        if len(points) != len(normals):
+            raise ValueError("Points and normals must have the same length")
+
+        for point, normal in zip(points, normals):
+            end = point + normal * scale
+
+            if arrow:
+                self.ax.quiver(
+                    point.x, point.y, point.z,
+                    normal.x * scale, normal.y * scale, normal.z * scale,
+                    color=color,
+                    linewidth=linewidth,
+                    alpha=alpha,
+                    arrow_length_ratio=0.3
+                )
+            else:
+                self.ax.plot(
+                    [point.x, end.x],
+                    [point.y, end.y],
+                    [point.z, end.z],
+                    color=color,
+                    linewidth=linewidth,
+                    alpha=alpha
+                )
+
+    def draw_curve_frames(
+        self,
+        frames: List[coord3],
+        scale: float = 0.3,
+        linewidth: float = 1.5,
+        alpha: float = 0.7,
+        skip: int = 1
+    ):
+        """
+        绘制曲线上的坐标系场
+
+        Args:
+            frames: 坐标系列表
+            scale: 坐标轴长度
+            linewidth: 线宽
+            alpha: 透明度
+            skip: 跳过间隔(每skip个绘制一个)
+        """
+        for i, frame in enumerate(frames):
+            if i % skip == 0:
+                self.draw_coord_system(
+                    frame,
+                    scale=scale,
+                    linewidth=linewidth,
+                    alpha=alpha
+                )
+
+    def draw_complete_curve(
+        self,
+        points: List[vec3],
+        tangents: Optional[List[vec3]] = None,
+        normals: Optional[List[vec3]] = None,
+        frames: Optional[List[coord3]] = None,
+        curve_color: str = 'black',
+        tangent_scale: float = 0.5,
+        normal_scale: float = 0.5,
+        frame_scale: float = 0.3,
+        frame_skip: int = 5,
+        show_world_coord: bool = True
+    ):
+        """
+        绘制完整的曲线及其几何属性
+
+        Args:
+            points: 曲线顶点
+            tangents: 切线向量(可选)
+            normals: 法线向量(可选)
+            frames: 坐标系列表(可选)
+            curve_color: 曲线颜色
+            tangent_scale: 切线长度缩放
+            normal_scale: 法线长度缩放
+            frame_scale: 坐标系轴长度
+            frame_skip: 坐标系绘制间隔
+            show_world_coord: 是否显示世界坐标系
+
+        Note:
+            如果提供了 frames (Frenet标架)，将使用RGB颜色方案绘制完整标架，
+            此时会忽略单独的 tangents 和 normals 参数，避免颜色混淆。
+        """
+        # 绘制世界坐标系
+        if show_world_coord:
+            self.draw_world_coord(scale=1.0)
+
+        # 绘制曲线
+        self.draw_curve_vertices(points, color=curve_color, label="Curve")
+
+        # 如果提供了完整标架，优先使用RGB标架，不再绘制单独的切线/法线
+        if frames is not None:
+            # 绘制完整Frenet标架 (红=T, 绿=N, 蓝=B)
+            self.draw_curve_frames(frames, scale=frame_scale, skip=frame_skip)
+        else:
+            # 否则绘制单独的切线和法线 (橙色/紫色)
+            if tangents is not None:
+                self.draw_tangents(points, tangents, scale=tangent_scale)
+
+            if normals is not None:
+                self.draw_normals(points, normals, scale=normal_scale)
+
+        # 设置等比例
+        self.set_equal_aspect()
+
+
+class ParametricCurve:
+    """
+    参数化曲线类
+
+    提供曲线的几何属性计算:
+    - 位置
+    - 切线
+    - 法线
+    - 副法线
+    - Frenet标架
+    """
+
+    def __init__(
+        self,
+        position_func: Callable[[float], vec3],
+        t_range: Tuple[float, float] = (0, 1),
+        num_points: int = 100
+    ):
+        """
+        初始化参数化曲线
+
+        Args:
+            position_func: 位置函数 r(t) -> vec3
+            t_range: 参数范围 (t_min, t_max)
+            num_points: 采样点数
+        """
+        self.position_func = position_func
+        self.t_range = t_range
+        self.num_points = num_points
+        self.h = 1e-6  # 数值微分步长
+
+    def position(self, t: float) -> vec3:
+        """计算位置"""
+        return self.position_func(t)
+
+    def tangent(self, t: float, normalized: bool = True) -> vec3:
+        """
+        计算切线 dr/dt
+
+        Args:
+            t: 参数值
+            normalized: 是否归一化
+        """
+        r_plus = self.position_func(t + self.h)
+        r_minus = self.position_func(t - self.h)
+        tangent = (r_plus - r_minus) * (1.0 / (2.0 * self.h))
+
+        if normalized:
+            length = (tangent.x**2 + tangent.y**2 + tangent.z**2) ** 0.5
+            if length > 1e-10:
+                tangent = tangent * (1.0 / length)
+
+        return tangent
+
+    def second_derivative(self, t: float) -> vec3:
+        """计算二阶导数 d²r/dt²"""
+        r_plus = self.position_func(t + self.h)
+        r_center = self.position_func(t)
+        r_minus = self.position_func(t - self.h)
+
+        d2r = (r_plus + r_minus - r_center * 2.0) * (1.0 / (self.h * self.h))
+        return d2r
+
+    def normal(self, t: float, normalized: bool = True) -> vec3:
+        """
+        计算主法线(指向曲率中心)
+
+        使用Frenet-Serret公式:
+        N = (dT/dt) / |dT/dt|
+        其中 T = (dr/dt) / |dr/dt|
+
+        Args:
+            t: 参数值
+            normalized: 是否归一化
+        """
+        # 计算 T(t+h) 和 T(t-h)
+        T_plus = self.tangent(t + self.h, normalized=True)
+        T_minus = self.tangent(t - self.h, normalized=True)
+
+        # 数值微分: dT/dt ≈ (T(t+h) - T(t-h)) / (2h)
+        dT_dt = (T_plus - T_minus) * (1.0 / (2.0 * self.h))
+
+        # 主法线是 dT/dt 的归一化
+        length = (dT_dt.x**2 + dT_dt.y**2 + dT_dt.z**2) ** 0.5
+
+        if length > 1e-10:
+            N = dT_dt * (1.0 / length) if normalized else dT_dt
+        else:
+            # 如果长度太小,返回一个默认值
+            N = vec3(0, 0, 1)
+
+        return N
+
+    def binormal(self, t: float, normalized: bool = True) -> vec3:
+        """
+        计算副法线 B = T × N
+
+        Args:
+            t: 参数值
+            normalized: 是否归一化
+        """
+        T = self.tangent(t, normalized=True)
+        N = self.normal(t, normalized=True)
+        B = T.cross(N)
+
+        if normalized:
+            length = (B.x**2 + B.y**2 + B.z**2) ** 0.5
+            if length > 1e-10:
+                B = B * (1.0 / length)
+
+        return B
+
+    def frenet_frame(self, t: float) -> coord3:
+        """
+        计算Frenet标架 {T, N, B}
+
+        Args:
+            t: 参数值
+
+        Returns:
+            coord3对象,其中:
+            - o: 位置
+            - ux: 切线 T (绘制时为红色)
+            - uy: 主法线 N (绘制时为绿色)
+            - uz: 副法线 B (绘制时为蓝色)
+
+        颜色映射:
+            - 切线 T = X轴 = 红色
+            - 主法线 N = Y轴 = 绿色
+            - 副法线 B = Z轴 = 蓝色
+        """
+        frame = coord3()
+        frame.o = self.position(t)
+        frame.ux = self.tangent(t, normalized=True)  # T → 红色
+        frame.uy = self.normal(t, normalized=True)    # N → 绿色
+        frame.uz = self.binormal(t, normalized=True)  # B → 蓝色
+
+        return frame
+
+    def sample_points(self) -> List[vec3]:
+        """采样曲线点"""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.position(t) for t in t_values]
+
+    def sample_tangents(self) -> List[vec3]:
+        """采样切线"""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.tangent(t) for t in t_values]
+
+    def sample_normals(self) -> List[vec3]:
+        """采样主法线"""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.normal(t) for t in t_values]
+
+    def sample_frames(self) -> List[coord3]:
+        """采样Frenet标架"""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.frenet_frame(t) for t in t_values]
+
+
+# ========== 便捷函数 ==========
+
+def visualize_coord_system(
+    coord: coord3,
+    scale: float = 1.0,
+    figsize: Tuple[int, int] = (10, 8),
+    show: bool = True,
+    save_path: Optional[str] = None
+):
+    """
+    快速可视化单个坐标系
+
+    Args:
+        coord: 坐标系对象
+        scale: 轴长度
+        figsize: 图形大小
+        show: 是否显示
+        save_path: 保存路径(可选)
+    """
+    vis = CoordinateSystemVisualizer(figsize=figsize)
+    vis.draw_world_coord(scale=scale * 0.8)
+    vis.draw_coord_system(coord, scale=scale, label_prefix="Frame-")
+    vis.set_equal_aspect()
+
+    if save_path:
+        vis.save(save_path)
+    if show:
+        vis.show()
+
+
+def visualize_curve(
+    curve: ParametricCurve,
+    show_tangents: bool = True,
+    show_normals: bool = True,
+    show_frames: bool = False,
+    frame_skip: int = 5,
+    figsize: Tuple[int, int] = (12, 9),
+    show: bool = True,
+    save_path: Optional[str] = None
+):
+    """
+    快速可视化参数化曲线
+
+    Args:
+        curve: 参数化曲线对象
+        show_tangents: 是否显示切线
+        show_normals: 是否显示法线
+        show_frames: 是否显示完整坐标系
+        frame_skip: 坐标系绘制间隔
+        figsize: 图形大小
+        show: 是否显示
+        save_path: 保存路径(可选)
+    """
+    vis = CurveVisualizer(figsize=figsize)
+
+    points = curve.sample_points()
+    tangents = curve.sample_tangents() if show_tangents else None
+    normals = curve.sample_normals() if show_normals else None
+    frames = curve.sample_frames() if show_frames else None
+
+    vis.draw_complete_curve(
+        points=points,
+        tangents=tangents,
+        normals=normals,
+        frames=frames,
+        frame_skip=frame_skip
+    )
+
+    if save_path:
+        vis.save(save_path)
+    if show:
+        vis.show()
+
+
+# ========== Export ==========
+
+__all__ = [
+    # Classes
+    'CoordinateSystemVisualizer',
+    'CurveVisualizer',
+    'ParametricCurve',
+
+    # Functions
+    'visualize_coord_system',
+    'visualize_curve',
+]