coordinate-system 2.4.2__cp313-cp313-win_amd64.whl → 2.5.0__cp313-cp313-win_amd64.whl

coordinate_system/intrinsic_gradient_curvature.py

@@ -0,0 +1,533 @@
+"""
+Intrinsic Gradient Operator Based Curvature Calculation Module
+==============================================================
+
+This module implements surface curvature calculation based on the Intrinsic Gradient Operator method.
+The method defines the intrinsic gradient operator G_μ = (c(u+h) - c(u))/h, transforming the 
+calculation of surface geometric properties into the analysis of coordinate system changes.
+
+Theoretical Basis:
+-----------------
+1. Intrinsic gradient operator definition: G_μ = (c(u+h_μ) - c(u))/h_μ
+   where c(u,v) is the intrinsic frame on the surface
+
+2. Geometric meaning of intrinsic gradient operator:
+   - G_μ.ux, G_μ.uy: rotation and deformation of tangent space
+   - G_μ.uz: rate of change of normal vector, i.e., ∂n/∂μ
+   - G_μ.s: change of metric scaling factor
+
+3. Second fundamental form calculation:
+   - L = -∂n/∂u · f_u = -G_u.uz · f_u
+   - M = -1/2(∂n/∂u · f_v + ∂n/∂v · f_u)
+   - N = -∂n/∂v · f_v = -G_v.uz · f_v
+
+4. Gaussian curvature: K = (LN - M²) / det(g)
+
+Advantages:
+----------
+- Numerical stability: avoids complex tensor operations and high-order derivatives
+- Geometric intuition: transforms curvature concepts into coordinate system change analysis
+- Computational efficiency: mainly involves basic vector operations and finite differences
+- Intrinsic-embedding synergy: combines advantages of intrinsic and embedding frames
+
+Author: PanGuoJun
+Version: 1.0.0
+Date: 2025-10-30
+"""
+
+import numpy as np
+from typing import Tuple, Optional, Dict, Union
+from .coordinate_system import coord3, vec3
+from .differential_geometry import Surface, MetricTensor
+
+
+class IntrinsicGradientOperator:
+    """
+    Intrinsic Gradient Operator Class
+
+    Implements calculation of intrinsic gradient operator G_μ = (c(u+h) - c(u))/h,
+    used for analyzing local changes in surface geometric properties.
+    """
+
+    def __init__(self, surface: Surface, step_size: float = 1e-4):
+        """
+        Initialize intrinsic gradient operator
+
+        Parameters:
+            surface: Surface object
+            step_size: finite difference step size (default: 1e-4)
+        """
+        self.surface = surface
+        self.h = step_size
+
+    def compute_intrinsic_frame(self, u: float, v: float) -> coord3:
+        """
+        Compute intrinsic frame c(u,v)
+
+        Intrinsic frame consists of orthonormalized tangent vectors and normal vector:
+        c = (e_u, e_v, n)
+        where e_u, e_v are unit tangent vectors obtained through Gram-Schmidt orthogonalization
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            coord3 object containing orthonormalized basis vectors
+        """
+        # Compute tangent vectors
+        r_u = self.surface.tangent_u(u, v)
+        r_v = self.surface.tangent_v(u, v)
+
+        # Gram-Schmidt orthogonalization
+        e1 = r_u.normcopy()  # First basis vector: normalized r_u
+
+        # Second basis vector: projection of r_v onto orthogonal complement of e1
+        r_v_orth = r_v - e1 * r_v.dot(e1)
+        e2 = r_v_orth.normcopy()
+
+        # Third basis vector: normal vector
+        n = e1.cross(e2).normcopy()
+
+        # Create intrinsic frame
+        return coord3(e1, e2, n)
+
+    def compute_embedding_frame(self, u: float, v: float) -> coord3:
+        """
+        Compute embedding frame C(u,v)
+
+        Embedding frame preserves metric information through Gram-Schmidt orthogonalization 
+        while maintaining tangent vector lengths:
+        C = (f_u, f_v, n)
+        where f_u, f_v are orthogonalized tangent vectors with preserved lengths
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            coord3 object preserving metric information
+        """
+        # Compute tangent vectors
+        r_u = self.surface.tangent_u(u, v)
+        r_v = self.surface.tangent_v(u, v)
+
+        # Gram-Schmidt orthogonalization (preserving metric information)
+        e1 = r_u.normcopy()
+        e1_length = (r_u.x**2 + r_u.y**2 + r_u.z**2) ** 0.5
+
+        # Projection of r_v onto orthogonal complement of e1
+        proj = r_v.dot(e1)
+        r_v_orth = r_v - e1 * proj
+        e2 = r_v_orth.normcopy()
+        e2_length = (r_v_orth.x**2 + r_v_orth.y**2 + r_v_orth.z**2) ** 0.5
+
+        # Normal vector (already normalized)
+        n = e1.cross(e2).normcopy()
+
+        # Create embedding frame, preserving metric information
+        # Using 5-parameter constructor: coord3(origin, scale, ux, uy, uz)
+        origin = self.surface.position(u, v)
+        scale = vec3(e1_length, e2_length, 1.0)
+
+        return coord3(origin, scale, e1, e2, n)
+
+    def compute(self, u: float, v: float, direction: str = 'u') -> coord3:
+        """
+        Compute intrinsic gradient operator G_μ
+
+        Using definition: G_μ = (c(u+h) - c(u))/h
+
+        Parameters:
+            u, v: parameter coordinates
+            direction: 'u' or 'v', calculation direction
+
+        Returns:
+            coord3 object representing intrinsic gradient operator
+        """
+        # Compute intrinsic frame at center point
+        c_center = self.compute_intrinsic_frame(u, v)
+
+        # Compute intrinsic frame at shifted point
+        if direction == 'u':
+            c_shifted = self.compute_intrinsic_frame(u + self.h, v)
+        elif direction == 'v':
+            c_shifted = self.compute_intrinsic_frame(u, v + self.h)
+        else:
+            raise ValueError(f"direction must be 'u' or 'v', got: {direction}")
+
+        # Intrinsic gradient operator: G_μ = (c(u+h) - c(u))/h
+        # Note: coord3 subtraction normalizes scale to (1,1,1), need manual scaling
+        G_raw = c_shifted - c_center
+
+        # Divide by step size to get derivative
+        if abs(self.h) > 1e-14:
+            h_inv = 1.0 / self.h
+            # Scale the scale vector
+            scaled_s = vec3(G_raw.s.x * h_inv, G_raw.s.y * h_inv, G_raw.s.z * h_inv)
+            G = coord3(G_raw.o, scaled_s, G_raw.ux, G_raw.uy, G_raw.uz)
+        else:
+            G = G_raw
+
+        return G
+
+    def compute_both(self, u: float, v: float) -> Tuple[coord3, coord3]:
+        """
+        Compute intrinsic gradient operators in both directions simultaneously
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Tuple of (G_u, G_v)
+        """
+        G_u = self.compute(u, v, 'u')
+        G_v = self.compute(u, v, 'v')
+        return G_u, G_v
+
+
+class IntrinsicGradientCurvatureCalculator:
+    """
+    Curvature calculator based on intrinsic gradient operator
+
+    Uses intrinsic gradient operator method to calculate various surface curvatures:
+    1. Compute intrinsic gradient operators G_u, G_v
+    2. Extract normal vector derivatives ∂n/∂u, ∂n/∂v from G_u.uz, G_v.uz
+    3. Compute second fundamental form L, M, N
+    4. Compute Gaussian curvature K = (LN - M²)/det(g)
+    """
+
+    def __init__(self, surface: Surface, step_size: float = 1e-4):
+        """
+        Initialize curvature calculator
+
+        Parameters:
+            surface: Surface object
+            step_size: finite difference step size (default: 1e-4)
+                     Recommended range: 1e-5 to 1e-3
+        """
+        self.surface = surface
+        self.h = step_size
+        self.intrinsic_grad = IntrinsicGradientOperator(surface, step_size)
+
+    def compute_second_fundamental_form(self, u: float, v: float) -> Tuple[float, float, float]:
+        """
+        Compute second fundamental form coefficients L, M, N
+
+        Using intrinsic gradient operator method:
+        L = -∂n/∂u · r_u = -G_u.uz · r_u
+        M = -1/2(∂n/∂u · r_v + ∂n/∂v · r_u)
+        N = -∂n/∂v · r_v = -G_v.uz · r_v
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Tuple of (L, M, N)
+        """
+        # Compute intrinsic gradient operators
+        G_u, G_v = self.intrinsic_grad.compute_both(u, v)
+
+        # Compute tangent vectors
+        r_u = self.surface.tangent_u(u, v)
+        r_v = self.surface.tangent_v(u, v)
+
+        # Extract normal vector derivatives (stored in uz components)
+        dn_du = vec3(G_u.uz.x, G_u.uz.y, G_u.uz.z)
+        dn_dv = vec3(G_v.uz.x, G_v.uz.y, G_v.uz.z)
+
+        # Compute second fundamental form coefficients
+        L = -dn_du.dot(r_u)
+        M1 = -dn_du.dot(r_v)
+        M2 = -dn_dv.dot(r_u)
+        M = (M1 + M2) / 2.0  # Symmetrization
+        N = -dn_dv.dot(r_v)
+
+        return L, M, N
+
+    def compute_gaussian_curvature(self, u: float, v: float) -> float:
+        """
+        Compute Gaussian curvature using intrinsic gradient operator
+
+        Formula: K = (LN - M²) / det(g)
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Gaussian curvature K
+
+        Example:
+            >>> from coordinate_system import Sphere
+            >>> sphere = Sphere(radius=2.0)
+            >>> calc = IntrinsicGradientCurvatureCalculator(sphere)
+            >>> K = calc.compute_gaussian_curvature(np.pi/4, np.pi/6)
+            >>> print(f"K = {K:.6f}, theoretical = 0.250000")
+        """
+        # Compute embedding frame and metric
+        C = self.intrinsic_grad.compute_embedding_frame(u, v)
+        metric = MetricTensor.from_coord3(C)
+
+        # Compute second fundamental form
+        L, M, N = self.compute_second_fundamental_form(u, v)
+
+        # Gaussian curvature
+        if abs(metric.det) > 1e-14:
+            K = (L * N - M * M) / metric.det
+        else:
+            K = 0.0
+
+        return K
+
+    def compute_mean_curvature(self, u: float, v: float) -> float:
+        """
+        Compute mean curvature using intrinsic gradient operator
+
+        Formula: H = (EN - 2FM + GL) / (2·det(g))
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Mean curvature H
+        """
+        # Compute embedding frame and metric
+        C = self.intrinsic_grad.compute_embedding_frame(u, v)
+        metric = MetricTensor.from_coord3(C)
+
+        # Compute second fundamental form
+        L, M, N = self.compute_second_fundamental_form(u, v)
+
+        # Mean curvature
+        if abs(metric.det) > 1e-14:
+            H = (metric.G * L - 2 * metric.F * M + metric.E * N) / (2 * metric.det)
+        else:
+            H = 0.0
+
+        return H
+
+    def compute_principal_curvatures(self, u: float, v: float) -> Tuple[float, float]:
+        """
+        Compute principal curvatures
+
+        Principal curvatures are eigenvalues of shape operator S = g⁻¹h
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Tuple of principal curvatures (k1, k2) where |k1| >= |k2|
+        """
+        K = self.compute_gaussian_curvature(u, v)
+        H = self.compute_mean_curvature(u, v)
+
+        # Use formula: k1,2 = H ± √(H² - K)
+        discriminant = H * H - K
+        if discriminant < 0:
+            discriminant = 0
+
+        sqrt_disc = discriminant ** 0.5
+        k1 = H + sqrt_disc
+        k2 = H - sqrt_disc
+
+        return k1, k2
+
+    def compute_all_curvatures(self, u: float, v: float) -> Dict[str, Union[float, Tuple[float, float, float]]]:
+        """
+        Compute all curvature-related quantities
+
+        Parameters:
+            u, v: parameter coordinates
+
+        Returns:
+            Dictionary containing the following keys:
+            - 'K': Gaussian curvature
+            - 'H': Mean curvature
+            - 'k1', 'k2': Principal curvatures
+            - 'L', 'M', 'N': Second fundamental form coefficients
+            - 'det_g': Metric determinant
+        """
+        # Compute embedding frame and metric
+        C = self.intrinsic_grad.compute_embedding_frame(u, v)
+        metric = MetricTensor.from_coord3(C)
+
+        # Compute second fundamental form
+        L, M, N = self.compute_second_fundamental_form(u, v)
+
+        # Compute curvatures
+        if abs(metric.det) > 1e-14:
+            K = (L * N - M * M) / metric.det
+            H = (metric.G * L - 2 * metric.F * M + metric.E * N) / (2 * metric.det)
+        else:
+            K = 0.0
+            H = 0.0
+
+        # Principal curvatures
+        discriminant = max(0, H * H - K)
+        sqrt_disc = discriminant ** 0.5
+        k1 = H + sqrt_disc
+        k2 = H - sqrt_disc
+
+        return {
+            'K': K,
+            'H': H,
+            'k1': k1,
+            'k2': k2,
+            'L': L,
+            'M': M,
+            'N': N,
+            'det_g': metric.det,
+            'E': metric.E,
+            'F': metric.F,
+            'G': metric.G
+        }
+
+    def verify_against_sphere(self, u: float, v: float, radius: float) -> Dict[str, float]:
+        """
+        Verify curvature calculation on sphere
+
+        Used for testing and validating calculation correctness.
+        Theoretical values for sphere: K = 1/R², H = 1/R, k1 = k2 = 1/R
+
+        Parameters:
+            u, v: parameter coordinates
+            radius: sphere radius
+
+        Returns:
+            Dictionary containing computed values, theoretical values, and errors
+        """
+        results = self.compute_all_curvatures(u, v)
+
+        # Theoretical values
+        K_theory = 1.0 / (radius * radius)
+        H_theory = 1.0 / radius
+        k_theory = 1.0 / radius
+
+        # Error calculation
+        K_error = abs(results['K'] - K_theory) / K_theory * 100 if K_theory != 0 else 0
+        H_error = abs(results['H'] - H_theory) / H_theory * 100 if H_theory != 0 else 0
+        k1_error = abs(results['k1'] - k_theory) / k_theory * 100 if k_theory != 0 else 0
+        k2_error = abs(results['k2'] - k_theory) / k_theory * 100 if k_theory != 0 else 0
+
+        return {
+            'K_computed': results['K'],
+            'K_theory': K_theory,
+            'K_error_%': K_error,
+            'H_computed': results['H'],
+            'H_theory': H_theory,
+            'H_error_%': H_error,
+            'k1_computed': results['k1'],
+            'k1_theory': k_theory,
+            'k1_error_%': k1_error,
+            'k2_computed': results['k2'],
+            'k2_theory': k_theory,
+            'k2_error_%': k2_error
+        }
+
+
+# ========== Simplified Interface Functions ==========
+
+def intrinsic_gradient_gaussian_curvature(
+    surface: Surface,
+    u: float,
+    v: float,
+    step_size: float = 1e-4
+) -> float:
+    """
+    Compute Gaussian curvature using intrinsic gradient operator method (simplified interface)
+
+    Parameters:
+        surface: Surface object
+        u, v: parameter coordinates
+        step_size: finite difference step size (default: 1e-4)
+
+    Returns:
+        Gaussian curvature K
+
+    Example:
+        >>> from coordinate_system import Sphere
+        >>> from coordinate_system.intrinsic_gradient_curvature import intrinsic_gradient_gaussian_curvature
+        >>> import math
+        >>>
+        >>> sphere = Sphere(radius=2.0)
+        >>> K = intrinsic_gradient_gaussian_curvature(sphere, math.pi/4, math.pi/6)
+        >>> print(f"K = {K:.6f}")  # Should output K ≈ 0.250000
+    """
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_gaussian_curvature(u, v)
+
+
+def intrinsic_gradient_mean_curvature(
+    surface: Surface,
+    u: float,
+    v: float,
+    step_size: float = 1e-4
+) -> float:
+    """
+    Compute mean curvature using intrinsic gradient operator method (simplified interface)
+
+    Parameters:
+        surface: Surface object
+        u, v: parameter coordinates
+        step_size: finite difference step size (default: 1e-4)
+
+    Returns:
+        Mean curvature H
+    """
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_mean_curvature(u, v)
+
+
+def intrinsic_gradient_principal_curvatures(
+    surface: Surface,
+    u: float,
+    v: float,
+    step_size: float = 1e-4
+) -> Tuple[float, float]:
+    """
+    Compute principal curvatures using intrinsic gradient operator method (simplified interface)
+
+    Parameters:
+        surface: Surface object
+        u, v: parameter coordinates
+        step_size: finite difference step size (default: 1e-4)
+
+    Returns:
+        Tuple of principal curvatures (k1, k2)
+    """
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_principal_curvatures(u, v)
+
+
+def intrinsic_gradient_all_curvatures(
+    surface: Surface,
+    u: float,
+    v: float,
+    step_size: float = 1e-4
+) -> Dict[str, Union[float, Tuple[float, float, float]]]:
+    """
+    Compute all curvature quantities using intrinsic gradient operator method (simplified interface)
+
+    Parameters:
+        surface: Surface object
+        u, v: parameter coordinates
+        step_size: finite difference step size (default: 1e-4)
+
+    Returns:
+        Dictionary containing all curvature-related quantities
+    """
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_all_curvatures(u, v)
+
+
+# ========== Exports ==========
+
+__all__ = [
+    # Main classes
+    'IntrinsicGradientOperator',
+    'IntrinsicGradientCurvatureCalculator',
+
+    # Simplified interfaces
+    'intrinsic_gradient_gaussian_curvature',
+    'intrinsic_gradient_mean_curvature',
+    'intrinsic_gradient_principal_curvatures',
+    'intrinsic_gradient_all_curvatures',
+]

{coordinate_system-2.4.2.dist-info → coordinate_system-2.5.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: coordinate_system
-Version: 2.4.2
-Summary: High-performance 3D coordinate system library with machine-precision Gaussian curvature computation (0.000% error) using corrected antisymmetric extraction formula
+Version: 2.5.0
+Summary: High-performance 3D coordinate system library with Intrinsic Gradient Operator method for curvature computation, achieving machine-precision accuracy
 Home-page: https://github.com/panguojun/Coordinate-System
 Author: PanGuoJun
 Author-email: 18858146@qq.com
@@ -9,7 +9,7 @@ License: MIT
 Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
 Project-URL: Source, https://github.com/panguojun/Coordinate-System
 Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
-Keywords: 3d math vector quaternion coordinate-system geometry graphics spatial-computing differential-geometry curvature metric-tensor connection-operator discrete-geometry surface-curvature
+Keywords: 3d math vector quaternion coordinate-system geometry graphics spatial-computing differential-geometry curvature metric-tensor connection-operator discrete-geometry surface-curvature intrinsic-gradient-operator
 Platform: Windows
 Platform: Linux
 Platform: macOS

coordinate_system-2.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+coordinate_system/__init__.py,sha256=KuKtCyrBIQuv2iJeosXxLXcDCc20mkhoA6K1Ho9RwMQ,8000
+coordinate_system/coordinate_system.cp313-win_amd64.pyd,sha256=Rp2rgehlW-TUG3xwj9qjOWeOGNEqrPMo5U4rWu2WWns,494080
+coordinate_system/curvature.py,sha256=DWdLaDSrdcApN3ve_FY2R40h83H3xydOi9heMIMBvJw,26956
+coordinate_system/differential_geometry.py,sha256=P3GhfoZ8WHLSE3AmpzdlaEII7E9QsZsERiznXaBaKRc,17036
+coordinate_system/intrinsic_gradient_curvature.py,sha256=CVWMP5JgsKerIViii2vsFy-d_PCtB02ZIJ9fi8qmCVA,17680
+coordinate_system/two_stage_curvature.py,sha256=e4fYAhiUc8NwtBi5hz5se4if4i8zZzG8smNlWNwuJpw,7219
+coordinate_system-2.5.0.dist-info/LICENSE,sha256=tDnRkJxBYPzWdfh2gArRqrUPJxQZRZHJVs68qqBHIq4,1083
+coordinate_system-2.5.0.dist-info/METADATA,sha256=5xrBsPo6AqNG54t36EvxGktUhs1AAp7JYSppV_YX1aQ,19428
+coordinate_system-2.5.0.dist-info/WHEEL,sha256=4-iQBlRoDdX1wfPofc7KLWa5Cys4eZSgXs6GVU8fKlQ,101
+coordinate_system-2.5.0.dist-info/top_level.txt,sha256=R6LguuPPZ5esrIsDTqPGi9UxCvZPIXwn7KRKX87c79M,18
+coordinate_system-2.5.0.dist-info/RECORD,,

coordinate_system-2.4.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-coordinate_system/__init__.py,sha256=S-h_uoibcICCh5Tk_-Q6_aMwiCQ2vvKUgE4BzqCHpJ0,7086
-coordinate_system/coordinate_system.cp313-win_amd64.pyd,sha256=U-Qh2-MFB7aBMbPcipJSsQutvXqqowjTt7_46FdmZD4,494080
-coordinate_system/curvature.py,sha256=o2XQ7BryvzEyo9cCYhKleeRg6UzacfShSeYyGQkGnwo,26040
-coordinate_system/differential_geometry.py,sha256=yKn1pItaE-tepy-HAetkVfb-jRbDY7RKv68NKk4jsSQ,26345
-coordinate_system/two_stage_curvature.py,sha256=e4fYAhiUc8NwtBi5hz5se4if4i8zZzG8smNlWNwuJpw,7219
-coordinate_system-2.4.2.dist-info/LICENSE,sha256=tDnRkJxBYPzWdfh2gArRqrUPJxQZRZHJVs68qqBHIq4,1083
-coordinate_system-2.4.2.dist-info/METADATA,sha256=wSFHcdSVfkoMobvyqHL4GaKpOrALzGYCDS5eJXOZjB0,19414
-coordinate_system-2.4.2.dist-info/WHEEL,sha256=4-iQBlRoDdX1wfPofc7KLWa5Cys4eZSgXs6GVU8fKlQ,101
-coordinate_system-2.4.2.dist-info/top_level.txt,sha256=R6LguuPPZ5esrIsDTqPGi9UxCvZPIXwn7KRKX87c79M,18
-coordinate_system-2.4.2.dist-info/RECORD,,