coordinate-system 5.2.2__cp313-cp313-win_amd64.whl → 6.0.0__cp313-cp313-win_amd64.whl

coordinate_system/visualization.py

@@ -1,61 +1,99 @@
 """
-3D Coordinate System and Curve Visualization Module
-===================================================
+3D Coordinate System and Surface Visualization Module
+=====================================================
 
-This module provides tools for visualizing coordinate systems and curves in 3D space.
+Comprehensive visualization tools for coordinate systems, curves, and surfaces.
 
 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
+- Coordinate frame visualization with RGB color scheme (X=Red, Y=Green, Z=Blue)
+- Parametric curve visualization with Frenet frames
+- Surface rendering with curvature coloring
+- Frame field visualization on surfaces
+- Multiple view angles and animation support
+
+Author: Coordinate System Package
+Date: 2025-12-03
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 from mpl_toolkits.mplot3d import Axes3D
-from typing import List, Optional, Tuple, Callable, Union
+from matplotlib import cm
+from matplotlib.colors import Normalize, LinearSegmentedColormap
+import matplotlib.animation as animation
+from typing import List, Optional, Tuple, Callable, Union, Dict
 
 # 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
 
+# Import differential geometry for surface visualization
+try:
+    from .differential_geometry import Surface, Sphere, Torus, compute_gaussian_curvature, compute_mean_curvature
+except ImportError:
+    Surface = None
+    Sphere = None
+    Torus = None
+    compute_gaussian_curvature = None
+    compute_mean_curvature = None
+
+
+# ============================================================
+# Color Schemes
+# ============================================================
+
+# Curvature colormap: blue (negative) -> white (zero) -> red (positive)
+CURVATURE_COLORS = [
+    (0.0, 'blue'),
+    (0.5, 'white'),
+    (1.0, 'red')
+]
+
+def create_curvature_colormap():
+    """Create a diverging colormap for curvature visualization."""
+    return LinearSegmentedColormap.from_list('curvature',
+        [(0.0, 'blue'), (0.5, 'white'), (1.0, 'red')])
+
+
+# ============================================================
+# Coordinate System Visualizer
+# ============================================================
 
 class CoordinateSystemVisualizer:
     """
-    三维坐标系可视化工具
+    3D coordinate system visualization tool.
 
-    绘制坐标系时使用RGB颜色方案:
-    - X轴: 红色 (Red)
-    - Y轴: 绿色 (Green)
-    - Z轴: 蓝色 (Blue)
+    RGB color scheme:
+    - X axis: Red
+    - Y axis: Green
+    - Z axis: Blue
     """
 
-    def __init__(self, figsize: Tuple[int, int] = (12, 9)):
+    def __init__(self, figsize: Tuple[int, int] = (12, 9), dpi: int = 100):
         """
-        初始化可视化工具
+        Initialize visualizer.
 
         Args:
-            figsize: 图形大小 (width, height)
+            figsize: Figure size (width, height) in inches
+            dpi: Dots per inch for rendering
         """
-        self.fig = plt.figure(figsize=figsize)
+        self.fig = plt.figure(figsize=figsize, dpi=dpi)
         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)
+        """Configure axis style."""
+        self.ax.set_xlabel('X', fontsize=12, color='red', fontweight='bold')
+        self.ax.set_ylabel('Y', fontsize=12, color='green', fontweight='bold')
+        self.ax.set_zlabel('Z', fontsize=12, color='blue', fontweight='bold')
+        self.ax.grid(True, alpha=0.3, linestyle='--')
+        self.ax.xaxis.pane.fill = False
+        self.ax.yaxis.pane.fill = False
+        self.ax.zaxis.pane.fill = False
 
     def draw_coord_system(
         self,
@@ -63,49 +101,54 @@ class CoordinateSystemVisualizer:
         scale: float = 1.0,
         linewidth: float = 2.0,
         alpha: float = 0.8,
-        label_prefix: str = ""
+        label_prefix: str = "",
+        arrow_style: bool = True
     ):
         """
-        绘制单个坐标系
+        Draw a single coordinate frame.
 
         Args:
-            coord: coord3对象
-            scale: 轴长度缩放因子
-            linewidth: 线宽
-            alpha: 透明度
-            label_prefix: 标签前缀
+            coord: coord3 object
+            scale: Axis length scale factor
+            linewidth: Line width
+            alpha: Transparency
+            label_prefix: Label prefix for legend
+            arrow_style: Use arrow heads if True
         """
         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
-        )
+        if arrow_style:
+            # Use quiver for arrows
+            self.ax.quiver(
+                origin.x, origin.y, origin.z,
+                coord.ux.x * scale, coord.ux.y * scale, coord.ux.z * scale,
+                color='red', linewidth=linewidth, alpha=alpha,
+                arrow_length_ratio=0.15
+            )
+            self.ax.quiver(
+                origin.x, origin.y, origin.z,
+                coord.uy.x * scale, coord.uy.y * scale, coord.uy.z * scale,
+                color='green', linewidth=linewidth, alpha=alpha,
+                arrow_length_ratio=0.15
+            )
+            self.ax.quiver(
+                origin.x, origin.y, origin.z,
+                coord.uz.x * scale, coord.uz.y * scale, coord.uz.z * scale,
+                color='blue', linewidth=linewidth, alpha=alpha,
+                arrow_length_ratio=0.15
+            )
+        else:
+            # Use simple lines
+            x_end = origin + coord.ux * scale
+            y_end = origin + coord.uy * scale
+            z_end = origin + coord.uz * scale
+
+            self.ax.plot([origin.x, x_end.x], [origin.y, x_end.y], [origin.z, x_end.z],
+                        'r-', linewidth=linewidth, alpha=alpha)
+            self.ax.plot([origin.x, y_end.x], [origin.y, y_end.y], [origin.z, y_end.z],
+                        'g-', linewidth=linewidth, alpha=alpha)
+            self.ax.plot([origin.x, z_end.x], [origin.y, z_end.y], [origin.z, z_end.z],
+                        'b-', linewidth=linewidth, alpha=alpha)
 
     def draw_world_coord(
         self,
@@ -114,12 +157,12 @@ class CoordinateSystemVisualizer:
         linewidth: float = 3.0
     ):
         """
-        绘制世界坐标系
+        Draw world coordinate system.
 
         Args:
-            origin: 原点位置,默认为(0,0,0)
-            scale: 轴长度
-            linewidth: 线宽
+            origin: Origin position, default is (0, 0, 0)
+            scale: Axis length
+            linewidth: Line width
         """
         if origin is None:
             origin = vec3(0, 0, 0)
@@ -135,91 +178,381 @@ class CoordinateSystemVisualizer:
             label_prefix="World-"
         )
 
+    def draw_point(
+        self,
+        point: vec3,
+        color: str = 'black',
+        size: float = 50,
+        marker: str = 'o',
+        label: str = None
+    ):
+        """
+        Draw a single point.
+
+        Args:
+            point: Point position
+            color: Point color
+            size: Marker size
+            marker: Marker style
+            label: Label for legend
+        """
+        self.ax.scatter([point.x], [point.y], [point.z],
+                       c=color, s=size, marker=marker, label=label)
+
+    def draw_vector(
+        self,
+        start: vec3,
+        direction: vec3,
+        color: str = 'black',
+        linewidth: float = 2.0,
+        alpha: float = 0.8,
+        label: str = None
+    ):
+        """
+        Draw a vector as an arrow.
+
+        Args:
+            start: Starting point
+            direction: Direction vector
+            color: Arrow color
+            linewidth: Line width
+            alpha: Transparency
+            label: Label for legend
+        """
+        self.ax.quiver(
+            start.x, start.y, start.z,
+            direction.x, direction.y, direction.z,
+            color=color, linewidth=linewidth, alpha=alpha,
+            arrow_length_ratio=0.15, label=label
+        )
+
     def set_equal_aspect(self):
-        """设置等比例显示"""
-        # 获取当前所有数据的范围
+        """Set equal aspect ratio for all axes."""
         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 set_view(self, elev: float = 30, azim: float = 45):
+        """
+        Set camera view angle.
+
+        Args:
+            elev: Elevation angle in degrees
+            azim: Azimuth angle in degrees
+        """
+        self.ax.view_init(elev=elev, azim=azim)
+
+    def set_title(self, title: str, fontsize: int = 14):
+        """Set plot title."""
+        self.ax.set_title(title, fontsize=fontsize, fontweight='bold')
+
     def show(self):
-        """显示图形"""
-        self.ax.legend()
+        """Display the figure."""
+        self.ax.legend(loc='upper left')
         plt.tight_layout()
         plt.show()
 
     def save(self, filename: str, dpi: int = 300):
         """
-        保存图形
+        Save figure to file.
 
         Args:
-            filename: 文件名
-            dpi: 分辨率
+            filename: Output filename
+            dpi: Resolution
         """
-        self.ax.legend()
+        self.ax.legend(loc='upper left')
         plt.tight_layout()
         plt.savefig(filename, dpi=dpi, bbox_inches='tight')
+        print(f"Saved: {filename}")
 
 
-class CurveVisualizer(CoordinateSystemVisualizer):
+# ============================================================
+# Surface Visualizer
+# ============================================================
+
+class SurfaceVisualizer(CoordinateSystemVisualizer):
     """
-    曲线可视化工具
+    Surface visualization with curvature coloring.
 
-    支持绘制:
-    - 曲线顶点
-    - 切线
-    - 法线
-    - 完整坐标系场
+    Supports:
+    - Wireframe and surface rendering
+    - Gaussian/Mean curvature coloring
+    - Frame field overlay
+    - Normal vector visualization
     """
 
-    def __init__(self, figsize: Tuple[int, int] = (12, 9)):
+    def __init__(self, figsize: Tuple[int, int] = (14, 10), dpi: int = 100):
+        super().__init__(figsize, dpi)
+        self.colorbar = None
+
+    def draw_surface(
+        self,
+        surface: 'Surface',
+        u_range: Tuple[float, float] = (0.1, np.pi - 0.1),
+        v_range: Tuple[float, float] = (0, 2 * np.pi),
+        nu: int = 30,
+        nv: int = 40,
+        color: str = 'cyan',
+        alpha: float = 0.6,
+        wireframe: bool = True,
+        surface_plot: bool = True
+    ):
+        """
+        Draw a parametric surface.
+
+        Args:
+            surface: Surface object
+            u_range: Parameter u range
+            v_range: Parameter v range
+            nu: Number of u samples
+            nv: Number of v samples
+            color: Surface color
+            alpha: Transparency
+            wireframe: Show wireframe
+            surface_plot: Show filled surface
+        """
+        u = np.linspace(u_range[0], u_range[1], nu)
+        v = np.linspace(v_range[0], v_range[1], nv)
+        U, V = np.meshgrid(u, v)
+
+        X = np.zeros_like(U)
+        Y = np.zeros_like(U)
+        Z = np.zeros_like(U)
+
+        for i in range(nu):
+            for j in range(nv):
+                pos = surface.position(U[j, i], V[j, i])
+                X[j, i] = pos.x
+                Y[j, i] = pos.y
+                Z[j, i] = pos.z
+
+        if surface_plot:
+            self.ax.plot_surface(X, Y, Z, color=color, alpha=alpha,
+                                edgecolor='none', shade=True)
+
+        if wireframe:
+            self.ax.plot_wireframe(X, Y, Z, color='gray', alpha=0.3,
+                                  linewidth=0.5, rstride=2, cstride=2)
+
+    def draw_surface_curvature(
+        self,
+        surface: 'Surface',
+        curvature_type: str = 'gaussian',
+        u_range: Tuple[float, float] = (0.1, np.pi - 0.1),
+        v_range: Tuple[float, float] = (0, 2 * np.pi),
+        nu: int = 30,
+        nv: int = 40,
+        alpha: float = 0.8,
+        show_colorbar: bool = True,
+        step_size: float = 1e-3
+    ):
+        """
+        Draw surface with curvature coloring.
+
+        Args:
+            surface: Surface object
+            curvature_type: 'gaussian' or 'mean'
+            u_range: Parameter u range
+            v_range: Parameter v range
+            nu: Number of u samples
+            nv: Number of v samples
+            alpha: Transparency
+            show_colorbar: Show colorbar
+            step_size: Step size for curvature computation
+        """
+        if compute_gaussian_curvature is None:
+            raise ImportError("differential_geometry module not available")
+
+        u = np.linspace(u_range[0], u_range[1], nu)
+        v = np.linspace(v_range[0], v_range[1], nv)
+        U, V = np.meshgrid(u, v)
+
+        X = np.zeros_like(U)
+        Y = np.zeros_like(U)
+        Z = np.zeros_like(U)
+        K = np.zeros_like(U)
+
+        compute_func = compute_gaussian_curvature if curvature_type == 'gaussian' else compute_mean_curvature
+
+        for i in range(nu):
+            for j in range(nv):
+                pos = surface.position(U[j, i], V[j, i])
+                X[j, i] = pos.x
+                Y[j, i] = pos.y
+                Z[j, i] = pos.z
+                K[j, i] = compute_func(surface, U[j, i], V[j, i], step_size)
+
+        # Normalize curvature for coloring
+        K_abs_max = max(abs(K.min()), abs(K.max()))
+        if K_abs_max > 1e-10:
+            K_normalized = (K / K_abs_max + 1) / 2  # Map to [0, 1]
+        else:
+            K_normalized = np.ones_like(K) * 0.5
+
+        # Create colormap
+        cmap = create_curvature_colormap()
+        colors = cmap(K_normalized)
+
+        # Draw surface
+        surf = self.ax.plot_surface(X, Y, Z, facecolors=colors, alpha=alpha,
+                                   shade=True, linewidth=0, antialiased=True)
+
+        if show_colorbar:
+            norm = Normalize(vmin=-K_abs_max, vmax=K_abs_max)
+            sm = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+            sm.set_array([])
+            self.colorbar = self.fig.colorbar(sm, ax=self.ax, shrink=0.6, aspect=20,
+                                             label=f'{curvature_type.capitalize()} Curvature')
+
+    def draw_surface_normals(
+        self,
+        surface: 'Surface',
+        u_range: Tuple[float, float] = (0.1, np.pi - 0.1),
+        v_range: Tuple[float, float] = (0, 2 * np.pi),
+        nu: int = 8,
+        nv: int = 12,
+        scale: float = 0.3,
+        color: str = 'blue',
+        alpha: float = 0.8
+    ):
         """
-        初始化曲线可视化工具
+        Draw surface normal vectors.
 
         Args:
-            figsize: 图形大小
+            surface: Surface object
+            u_range: Parameter u range
+            v_range: Parameter v range
+            nu: Number of u samples
+            nv: Number of v samples
+            scale: Normal vector length
+            color: Vector color
+            alpha: Transparency
         """
-        super().__init__(figsize)
+        u = np.linspace(u_range[0], u_range[1], nu)
+        v = np.linspace(v_range[0], v_range[1], nv)
+
+        for ui in u:
+            for vi in v:
+                pos = surface.position(ui, vi)
+                n = surface.normal(ui, vi)
+
+                self.ax.quiver(
+                    pos.x, pos.y, pos.z,
+                    n.x * scale, n.y * scale, n.z * scale,
+                    color=color, alpha=alpha, arrow_length_ratio=0.2
+                )
+
+    def draw_surface_frames(
+        self,
+        surface: 'Surface',
+        u_range: Tuple[float, float] = (0.1, np.pi - 0.1),
+        v_range: Tuple[float, float] = (0, 2 * np.pi),
+        nu: int = 6,
+        nv: int = 8,
+        scale: float = 0.25,
+        linewidth: float = 1.5,
+        alpha: float = 0.8
+    ):
+        """
+        Draw frame field on surface.
+
+        Args:
+            surface: Surface object
+            u_range: Parameter u range
+            v_range: Parameter v range
+            nu: Number of u samples
+            nv: Number of v samples
+            scale: Frame axis length
+            linewidth: Line width
+            alpha: Transparency
+        """
+        u = np.linspace(u_range[0], u_range[1], nu)
+        v = np.linspace(v_range[0], v_range[1], nv)
+
+        for ui in u:
+            for vi in v:
+                pos = surface.position(ui, vi)
+                r_u = surface.tangent_u(ui, vi)
+                r_v = surface.tangent_v(ui, vi)
+                n = surface.normal(ui, vi)
+
+                # Normalize
+                r_u_norm = (r_u.x**2 + r_u.y**2 + r_u.z**2) ** 0.5
+                r_v_norm = (r_v.x**2 + r_v.y**2 + r_v.z**2) ** 0.5
+
+                if r_u_norm > 1e-10:
+                    r_u = r_u * (1.0 / r_u_norm)
+                if r_v_norm > 1e-10:
+                    r_v = r_v * (1.0 / r_v_norm)
+
+                # Draw frame (red=u, green=v, blue=normal)
+                self.ax.quiver(pos.x, pos.y, pos.z,
+                              r_u.x * scale, r_u.y * scale, r_u.z * scale,
+                              color='red', linewidth=linewidth, alpha=alpha,
+                              arrow_length_ratio=0.15)
+                self.ax.quiver(pos.x, pos.y, pos.z,
+                              r_v.x * scale, r_v.y * scale, r_v.z * scale,
+                              color='green', linewidth=linewidth, alpha=alpha,
+                              arrow_length_ratio=0.15)
+                self.ax.quiver(pos.x, pos.y, pos.z,
+                              n.x * scale, n.y * scale, n.z * scale,
+                              color='blue', linewidth=linewidth, alpha=alpha,
+                              arrow_length_ratio=0.15)
+
+
+# ============================================================
+# Curve Visualizer
+# ============================================================
+
+class CurveVisualizer(CoordinateSystemVisualizer):
+    """
+    Curve visualization with Frenet frame support.
+
+    Features:
+    - Curve path rendering
+    - Tangent, normal, binormal vectors
+    - Frenet frame field
+    - Animation support
+    """
+
+    def __init__(self, figsize: Tuple[int, int] = (12, 9), dpi: int = 100):
+        super().__init__(figsize, dpi)
 
     def draw_curve_vertices(
         self,
         points: List[vec3],
         color: str = 'black',
         linewidth: float = 2.0,
-        marker: str = 'o',
+        marker: str = '',
         markersize: float = 4,
-        alpha: float = 0.7,
+        alpha: float = 0.9,
         label: str = "Curve"
     ):
         """
-        绘制曲线顶点
+        Draw curve through vertices.
 
         Args:
-            points: 顶点列表
-            color: 颜色
-            linewidth: 线宽
-            marker: 标记样式
-            markersize: 标记大小
-            alpha: 透明度
-            label: 标签
+            points: Vertex list
+            color: Line color
+            linewidth: Line width
+            marker: Marker style (empty for no markers)
+            markersize: Marker size
+            alpha: Transparency
+            label: Legend label
         """
         if not points:
             return
@@ -228,109 +561,93 @@ class CurveVisualizer(CoordinateSystemVisualizer):
         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
-        )
+        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',
+        color: str = 'red',
         linewidth: float = 1.5,
-        alpha: float = 0.8,
-        arrow: bool = True
+        alpha: float = 0.8
     ):
         """
-        绘制切线
+        Draw tangent vectors.
 
         Args:
-            points: 曲线点列表
-            tangents: 切线向量列表
-            scale: 切线长度缩放
-            color: 颜色
-            linewidth: 线宽
-            alpha: 透明度
-            arrow: 是否使用箭头
+            points: Curve points
+            tangents: Tangent vectors
+            scale: Vector length scale
+            color: Vector color
+            linewidth: Line width
+            alpha: Transparency
         """
-        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
-                )
+            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.2
+            )
 
     def draw_normals(
         self,
         points: List[vec3],
         normals: List[vec3],
         scale: float = 0.5,
-        color: str = 'purple',
+        color: str = 'green',
         linewidth: float = 1.5,
-        alpha: float = 0.8,
-        arrow: bool = True
+        alpha: float = 0.8
     ):
         """
-        绘制法线
+        Draw normal vectors.
 
         Args:
-            points: 曲线点列表
-            normals: 法线向量列表
-            scale: 法线长度缩放
-            color: 颜色
-            linewidth: 线宽
-            alpha: 透明度
-            arrow: 是否使用箭头
+            points: Curve points
+            normals: Normal vectors
+            scale: Vector length scale
+            color: Vector color
+            linewidth: Line width
+            alpha: Transparency
         """
-        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
+            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.2
+            )
+
+    def draw_binormals(
+        self,
+        points: List[vec3],
+        binormals: List[vec3],
+        scale: float = 0.5,
+        color: str = 'blue',
+        linewidth: float = 1.5,
+        alpha: float = 0.8
+    ):
+        """
+        Draw binormal vectors.
 
-            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
-                )
+        Args:
+            points: Curve points
+            binormals: Binormal vectors
+            scale: Vector length scale
+            color: Vector color
+            linewidth: Line width
+            alpha: Transparency
+        """
+        for point, binormal in zip(points, binormals):
+            self.ax.quiver(
+                point.x, point.y, point.z,
+                binormal.x * scale, binormal.y * scale, binormal.z * scale,
+                color=color, linewidth=linewidth, alpha=alpha,
+                arrow_length_ratio=0.2
+            )
 
     def draw_curve_frames(
         self,
@@ -341,89 +658,87 @@ class CurveVisualizer(CoordinateSystemVisualizer):
         skip: int = 1
     ):
         """
-        绘制曲线上的坐标系场
+        Draw Frenet frames along curve.
 
         Args:
-            frames: 坐标系列表
-            scale: 坐标轴长度
-            linewidth: 线宽
-            alpha: 透明度
-            skip: 跳过间隔(每skip个绘制一个)
+            frames: List of coord3 frames
+            scale: Axis length
+            linewidth: Line width
+            alpha: Transparency
+            skip: Draw every nth frame
         """
         for i, frame in enumerate(frames):
             if i % skip == 0:
-                self.draw_coord_system(
-                    frame,
-                    scale=scale,
-                    linewidth=linewidth,
-                    alpha=alpha
-                )
+                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,
+        binormals: Optional[List[vec3]] = None,
         frames: Optional[List[coord3]] = None,
         curve_color: str = 'black',
         tangent_scale: float = 0.5,
         normal_scale: float = 0.5,
+        binormal_scale: float = 0.5,
         frame_scale: float = 0.3,
         frame_skip: int = 5,
         show_world_coord: bool = True
     ):
         """
-        绘制完整的曲线及其几何属性
+        Draw complete curve with geometric properties.
 
         Args:
-            points: 曲线顶点
-            tangents: 切线向量(可选)
-            normals: 法线向量(可选)
-            frames: 坐标系列表(可选)
-            curve_color: 曲线颜色
-            tangent_scale: 切线长度缩放
-            normal_scale: 法线长度缩放
-            frame_scale: 坐标系轴长度
-            frame_skip: 坐标系绘制间隔
-            show_world_coord: 是否显示世界坐标系
-
-        Note:
-            如果提供了 frames (Frenet标架)，将使用RGB颜色方案绘制完整标架，
-            此时会忽略单独的 tangents 和 normals 参数，避免颜色混淆。
-        """
-        # 绘制世界坐标系
+            points: Curve vertices
+            tangents: Tangent vectors (optional)
+            normals: Normal vectors (optional)
+            binormals: Binormal vectors (optional)
+            frames: Frenet frames (optional, overrides individual vectors)
+            curve_color: Curve color
+            tangent_scale: Tangent vector scale
+            normal_scale: Normal vector scale
+            binormal_scale: Binormal vector scale
+            frame_scale: Frame axis length
+            frame_skip: Frame drawing interval
+            show_world_coord: Show world coordinate system
+        """
         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)
+            # Use complete Frenet frames (RGB coloring)
             self.draw_curve_frames(frames, scale=frame_scale, skip=frame_skip)
         else:
-            # 否则绘制单独的切线和法线 (橙色/紫色)
+            # Draw individual vectors
             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)
+            if binormals is not None:
+                self.draw_binormals(points, binormals, scale=binormal_scale)
 
-        # 设置等比例
         self.set_equal_aspect()
 
 
+# ============================================================
+# Parametric Curve
+# ============================================================
+
 class ParametricCurve:
     """
-    参数化曲线类
-
-    提供曲线的几何属性计算:
-    - 位置
-    - 切线
-    - 法线
-    - 副法线
-    - Frenet标架
+    Parametric curve with Frenet frame computation.
+
+    Provides:
+    - Position r(t)
+    - Tangent T(t)
+    - Normal N(t)
+    - Binormal B(t)
+    - Frenet frame {T, N, B}
+    - Curvature and torsion
     """
 
     def __init__(
@@ -433,29 +748,29 @@ class ParametricCurve:
         num_points: int = 100
     ):
         """
-        初始化参数化曲线
+        Initialize parametric curve.
 
         Args:
-            position_func: 位置函数 r(t) -> vec3
-            t_range: 参数范围 (t_min, t_max)
-            num_points: 采样点数
+            position_func: Position function r(t) -> vec3
+            t_range: Parameter range (t_min, t_max)
+            num_points: Number of sample points
         """
         self.position_func = position_func
         self.t_range = t_range
         self.num_points = num_points
-        self.h = 1e-6  # 数值微分步长
+        self.h = 1e-6  # Numerical differentiation step
 
     def position(self, t: float) -> vec3:
-        """计算位置"""
+        """Compute position at parameter t."""
         return self.position_func(t)
 
     def tangent(self, t: float, normalized: bool = True) -> vec3:
         """
-        计算切线 dr/dt
+        Compute tangent vector T = dr/dt.
 
         Args:
-            t: 参数值
-            normalized: 是否归一化
+            t: Parameter value
+            normalized: Normalize to unit vector
         """
         r_plus = self.position_func(t + self.h)
         r_minus = self.position_func(t - self.h)
@@ -469,51 +784,40 @@ class ParametricCurve:
         return tangent
 
     def second_derivative(self, t: float) -> vec3:
-        """计算二阶导数 d²r/dt²"""
+        """Compute second derivative d^2r/dt^2."""
         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
+        return (r_plus + r_minus - r_center * 2.0) * (1.0 / (self.h * self.h))
 
     def normal(self, t: float, normalized: bool = True) -> vec3:
         """
-        计算主法线(指向曲率中心)
-
-        使用Frenet-Serret公式:
-        N = (dT/dt) / |dT/dt|
-        其中 T = (dr/dt) / |dr/dt|
+        Compute principal normal N = dT/ds / |dT/ds|.
 
         Args:
-            t: 参数值
-            normalized: 是否归一化
+            t: Parameter value
+            normalized: Normalize to unit vector
         """
-        # 计算 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
+        Compute binormal B = T x N.
 
         Args:
-            t: 参数值
-            normalized: 是否归一化
+            t: Parameter value
+            normalized: Normalize to unit vector
         """
         T = self.tangent(t, normalized=True)
         N = self.normal(t, normalized=True)
@@ -526,81 +830,113 @@ class ParametricCurve:
 
         return B
 
-    def frenet_frame(self, t: float) -> coord3:
+    def curvature(self, t: float) -> float:
         """
-        计算Frenet标架 {T, N, B}
+        Compute curvature kappa = |dT/ds|.
 
         Args:
-            t: 参数值
+            t: Parameter value
 
         Returns:
-            coord3对象,其中:
-            - o: 位置
-            - ux: 切线 T (绘制时为红色)
-            - uy: 主法线 N (绘制时为绿色)
-            - uz: 副法线 B (绘制时为蓝色)
+            Curvature value
+        """
+        T_plus = self.tangent(t + self.h, normalized=True)
+        T_minus = self.tangent(t - self.h, normalized=True)
+        dT_dt = (T_plus - T_minus) * (1.0 / (2.0 * self.h))
+
+        # Get speed |dr/dt|
+        dr_dt = (self.position_func(t + self.h) - self.position_func(t - self.h)) * (1.0 / (2.0 * self.h))
+        speed = (dr_dt.x**2 + dr_dt.y**2 + dr_dt.z**2) ** 0.5
+
+        if speed > 1e-10:
+            kappa = (dT_dt.x**2 + dT_dt.y**2 + dT_dt.z**2) ** 0.5 / speed
+        else:
+            kappa = 0.0
 
-        颜色映射:
-            - 切线 T = X轴 = 红色
-            - 主法线 N = Y轴 = 绿色
-            - 副法线 B = Z轴 = 蓝色
+        return kappa
+
+    def frenet_frame(self, t: float) -> coord3:
+        """
+        Compute Frenet frame {T, N, B}.
+
+        Returns coord3 with:
+        - o: Position
+        - ux: Tangent T (red)
+        - uy: Normal N (green)
+        - uz: Binormal B (blue)
         """
         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 → 蓝色
-
+        frame.ux = self.tangent(t, normalized=True)
+        frame.uy = self.normal(t, normalized=True)
+        frame.uz = self.binormal(t, normalized=True)
         return frame
 
     def sample_points(self) -> List[vec3]:
-        """采样曲线点"""
+        """Sample curve positions."""
         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]:
-        """采样切线"""
+        """Sample tangent vectors."""
         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]:
-        """采样主法线"""
+        """Sample normal vectors."""
         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_binormals(self) -> List[vec3]:
+        """Sample binormal vectors."""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.binormal(t) for t in t_values]
+
     def sample_frames(self) -> List[coord3]:
-        """采样Frenet标架"""
+        """Sample Frenet frames."""
         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 sample_curvature(self) -> List[float]:
+        """Sample curvature values."""
+        t_min, t_max = self.t_range
+        t_values = np.linspace(t_min, t_max, self.num_points)
+        return [self.curvature(t) for t in t_values]
 
-# ========== 便捷函数 ==========
+
+# ============================================================
+# Convenience Functions
+# ============================================================
 
 def visualize_coord_system(
     coord: coord3,
     scale: float = 1.0,
     figsize: Tuple[int, int] = (10, 8),
     show: bool = True,
-    save_path: Optional[str] = None
+    save_path: Optional[str] = None,
+    title: str = "Coordinate System"
 ):
     """
-    快速可视化单个坐标系
+    Quick visualization of a single coordinate frame.
 
     Args:
-        coord: 坐标系对象
-        scale: 轴长度
-        figsize: 图形大小
-        show: 是否显示
-        save_path: 保存路径(可选)
+        coord: Coordinate frame
+        scale: Axis length
+        figsize: Figure size
+        show: Display figure
+        save_path: Save path (optional)
+        title: Plot title
     """
     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()
+    vis.set_title(title)
 
     if save_path:
         vis.save(save_path)
@@ -610,41 +946,99 @@ def visualize_coord_system(
 
 def visualize_curve(
     curve: ParametricCurve,
-    show_tangents: bool = True,
-    show_normals: bool = True,
-    show_frames: bool = False,
+    show_tangents: bool = False,
+    show_normals: bool = False,
+    show_binormals: bool = False,
+    show_frames: bool = True,
     frame_skip: int = 5,
     figsize: Tuple[int, int] = (12, 9),
     show: bool = True,
-    save_path: Optional[str] = None
+    save_path: Optional[str] = None,
+    title: str = "Parametric Curve"
 ):
     """
-    快速可视化参数化曲线
+    Quick visualization of a parametric curve.
 
     Args:
-        curve: 参数化曲线对象
-        show_tangents: 是否显示切线
-        show_normals: 是否显示法线
-        show_frames: 是否显示完整坐标系
-        frame_skip: 坐标系绘制间隔
-        figsize: 图形大小
-        show: 是否显示
-        save_path: 保存路径(可选)
+        curve: Parametric curve object
+        show_tangents: Show tangent vectors
+        show_normals: Show normal vectors
+        show_binormals: Show binormal vectors
+        show_frames: Show complete Frenet frames
+        frame_skip: Frame drawing interval
+        figsize: Figure size
+        show: Display figure
+        save_path: Save path (optional)
+        title: Plot title
     """
     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
+    tangents = curve.sample_tangents() if show_tangents and not show_frames else None
+    normals = curve.sample_normals() if show_normals and not show_frames else None
+    binormals = curve.sample_binormals() if show_binormals and not show_frames else None
     frames = curve.sample_frames() if show_frames else None
 
     vis.draw_complete_curve(
         points=points,
         tangents=tangents,
         normals=normals,
+        binormals=binormals,
         frames=frames,
         frame_skip=frame_skip
     )
+    vis.set_title(title)
+
+    if save_path:
+        vis.save(save_path)
+    if show:
+        vis.show()
+
+
+def visualize_surface(
+    surface: 'Surface',
+    curvature_type: Optional[str] = None,
+    show_normals: bool = False,
+    show_frames: bool = False,
+    u_range: Tuple[float, float] = (0.1, np.pi - 0.1),
+    v_range: Tuple[float, float] = (0, 2 * np.pi),
+    figsize: Tuple[int, int] = (14, 10),
+    show: bool = True,
+    save_path: Optional[str] = None,
+    title: str = "Surface"
+):
+    """
+    Quick visualization of a parametric surface.
+
+    Args:
+        surface: Surface object
+        curvature_type: 'gaussian' or 'mean' for curvature coloring (None for plain)
+        show_normals: Show normal vectors
+        show_frames: Show frame field
+        u_range: Parameter u range
+        v_range: Parameter v range
+        figsize: Figure size
+        show: Display figure
+        save_path: Save path (optional)
+        title: Plot title
+    """
+    vis = SurfaceVisualizer(figsize=figsize)
+
+    if curvature_type:
+        vis.draw_surface_curvature(surface, curvature_type=curvature_type,
+                                  u_range=u_range, v_range=v_range)
+    else:
+        vis.draw_surface(surface, u_range=u_range, v_range=v_range)
+
+    if show_normals:
+        vis.draw_surface_normals(surface, u_range=u_range, v_range=v_range)
+
+    if show_frames:
+        vis.draw_surface_frames(surface, u_range=u_range, v_range=v_range)
+
+    vis.draw_world_coord(scale=0.5)
+    vis.set_equal_aspect()
+    vis.set_title(title)
 
     if save_path:
         vis.save(save_path)
@@ -652,15 +1046,24 @@ def visualize_curve(
         vis.show()
 
 
-# ========== Export ==========
+# ============================================================
+# Export
+# ============================================================
 
 __all__ = [
-    # Classes
+    # Visualizer classes
     'CoordinateSystemVisualizer',
     'CurveVisualizer',
+    'SurfaceVisualizer',
+
+    # Curve class
     'ParametricCurve',
 
-    # Functions
+    # Convenience functions
     'visualize_coord_system',
     'visualize_curve',
+    'visualize_surface',
+
+    # Utility
+    'create_curvature_colormap',
 ]