Metadata-Version: 2.1
Name: coordinate_system
Version: 6.0.0
Summary: High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, spectral transforms, and professional curvature visualization
Home-page: https://github.com/panguojun/Coordinate-System
Author: PanGuoJun
Author-email: 18858146@qq.com
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 curve-interpolation c2-continuity frenet-frames fourier-transform operator-overloading quantum-coordinates heisenberg-uncertainty visualization rgb-frames catmull-rom squad intrinsic-gradient spectral-analysis surface-visualization
Platform: Windows
Platform: Linux
Platform: macOS
Platform: Android
Platform: iOS
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: matplotlib>=3.3.0

# Coordinate System Library

**High-performance 3D coordinate system and differential geometry library for Python**

[![PyPI version](https://badge.fury.io/py/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
[![Python](https://img.shields.io/pypi/pyversions/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue.svg)](https://pypi.org/project/coordinate-system/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Author:** PanGuoJun
**Version:** 6.0.0
**License:** MIT

---

## 🆕 What's New in v6.0.0 (2025-12-03)

### Major Architecture Refactoring

**Unified Differential Geometry Module** - Complete integration of curvature computation methods

- **Merged Module**: `differential_geometry.py` now contains both classical and intrinsic gradient methods
- **Dual Method Support**:
  - Intrinsic gradient method (default): `compute_gaussian_curvature()`, `compute_mean_curvature()`
  - Classical method: `gaussian_curvature_classical()`, `mean_curvature_classical()`
- **Backward Compatibility**: Old function names still work as aliases
- **High-Order Finite Differences**: 5-point formulas with O(h⁴) accuracy
- **All English Documentation**: Complete internationalization for global distribution

**Unified Quantum Frame Module** - Complex frame algebra with spectral analysis

- **Merged Module**: `qframes.py` combines complex quantum frames with Fourier spectral transforms
- **Core Concept**: Q ∈ ℂ as quantum scale factor
- **Integrated Spectral Transforms**: Now part of QFrame class methods
- **Dirac Notation**: Moved to optional export (incompatible with complex frame symbols)
- **GPU Acceleration**: CuPy support for large-scale spectral computations
- **Cleaner API**: Single unified interface for quantum frame operations

**Enhanced Visualization Module** - Professional surface and curvature rendering

- **New Class**: `SurfaceVisualizer` with curvature coloring support
- **Curvature Visualization**: Diverging colormap (blue-white-red) for Gaussian/Mean curvature
- **Surface Frame Fields**: RGB-coded tangent frames (red=u direction, green=v direction, blue=normal)
- **Enhanced Curve Rendering**: Binormal support, improved styling
- **Integration**: Direct support for differential_geometry surfaces
- **Convenience Functions**: `visualize_surface()` for quick visualization

### Breaking Changes

- `curvature.py` removed - functionality merged into `differential_geometry.py`
- `qframesnew.py` removed - functionality merged into `qframes.py`
- `fourier_spectral.py` now a compatibility wrapper with deprecation warnings
- Default curvature methods now use intrinsic gradient (more accurate for complex surfaces)

### Migration Guide

```python
# Old code (still works with deprecation warnings):
from coordinate_system import fourier_spectral
from coordinate_system import curvature

# New code (recommended):
from coordinate_system import qframes
from coordinate_system import differential_geometry

# Or use the unified imports:
from coordinate_system import (
    QFrame, spectral_transform, inverse_spectral_transform,
    compute_gaussian_curvature, compute_mean_curvature,
    SurfaceVisualizer, visualize_surface
)
```

---

## What's New in v5.2.1 (2025-12-01)

### Fourier Frames with Operator Overloading

**Module: `fourier_frames`** - Elegant quantum coordinate transformations

- **Operator Overloading Support**: Intuitive syntax for Fourier transforms
  - `F_p @ psi` - Matrix multiplication operator
  - `F_p * psi` - Multiplication operator
  - `psi | F_p` - Bra-ket notation
  - `~F_x` - Dual frame operator
- **Quantum State Representation**: `QuantumState` and `StateVector` classes
- **Heisenberg Uncertainty**: Built-in uncertainty principle computations
- **Position <-> Momentum Transforms**: Seamless coordinate basis transformations

### C2-Continuous Curve Interpolation

**Module: `curve_interpolation`** - Second-order smooth curves

- **C2-Continuity**: Catmull-Rom spline for position interpolation
- **SQUAD Interpolation**: Spherical Quadrangle for smooth quaternion interpolation
- **13x Smoother**: Reduced maximum curvature from 13.93 to 1.05

### Handedness Control

- ✨ **New**: C++ level handedness control (`set_handedness('left'/'right')`)
- 🔧 **Fixed**: Frenet frames now respect coordinate system handedness
- 📚 **Improved**: Global handedness setting for consistent behavior

---

## Features

### Core Components

**C++ Performance Layer:**
- **vec3** - 3D vector with comprehensive operations
- **vec2** - 2D vector for parametric coordinates
- **quat** - Quaternion for 3D rotations
- **coord3** - Complete 3D coordinate system (position, rotation, scale)

**Advanced Mathematics Modules:**
- **differential_geometry** - Surface analysis with dual curvature methods
- **qframes** - Quantum frame algebra with spectral transforms
- **visualization** - Professional 3D rendering for geometry and curvature
- **curve_interpolation** - C2-continuous curve and frame interpolation

### Operations

- Vector arithmetic (+, -, *, /)
- Dot product, cross product (left-handed system)
- Vector projection, reflection
- Linear interpolation (lerp)
- Spherical linear interpolation (slerp)
- Coordinate system transformations
- Euler angle conversion
- Gaussian and mean curvature computation
- Spectral analysis and Fourier transforms

### Performance

- Written in optimized C++17
- Python bindings via pybind11
- Over 1,000,000 operations per second
- GPU acceleration for spectral transforms (optional)

### Platform Support

- ✅ Windows (7, 10, 11)
- ✅ Linux (Ubuntu, Debian, CentOS, etc.)
- ✅ macOS (10.14+)

---

## 📚 Documentation

### Mathematical Foundation

For a comprehensive understanding of the mathematical principles behind coordinate systems, vectors, quaternions, and differential geometry, see our detailed guide:

**[📖 Mathematical Foundation of Coordinate Systems](https://github.com/panguojun/Coordinate-System)**

### Module Documentation

- [Curve Interpolation Guide](CURVE_INTERPOLATION_README.md)
- [C2 Interpolation Guide](C2_INTERPOLATION_GUIDE.md)

---

## Installation

### From PyPI (Recommended)

```bash
pip install coordinate-system
```

### From Source

```bash
git clone https://github.com/panguojun/Coordinate-System.git
cd Coordinate-System
pip install .
```

---

## Quick Start

```python
from coordinate_system import vec3, quat, coord3

# Create vectors
v1 = vec3(1, 2, 3)
v2 = vec3(4, 5, 6)

# Vector operations
v3 = v1 + v2              # Addition: vec3(5, 7, 9)
dot = v1.dot(v2)          # Dot product: 32.0
cross = v1.cross(v2)      # Cross product (left-handed)
length = v1.length()      # Length: 3.742
normalized = v1.normcopy() # Unit vector

# Quaternion rotation
axis = vec3(0, 0, 1)      # Z axis
q = quat(1.5708, axis)    # 90 degrees rotation
rotated = q * v1          # Rotate v1

# Coordinate systems
frame = coord3.from_angle(1.57, vec3(0, 0, 1))  # Frame rotated 90°
world_pos = v1 * frame    # Transform to world space
local_pos = world_pos / frame  # Transform back to local

# Differential geometry
from coordinate_system import Sphere, compute_gaussian_curvature

sphere = Sphere(radius=1.0)
K = compute_gaussian_curvature(sphere, u=0.5, v=0.5)  # K = 1.0 for unit sphere

# Visualization
from coordinate_system import visualize_surface

visualize_surface(sphere, curvature_type='gaussian', show_colorbar=True)
```

---

## Module Guide

### Core Classes (C++ Bindings)

#### vec3 - 3D Vector

```python
from coordinate_system import vec3

# Constructors
v = vec3()              # Zero vector (0, 0, 0)
v = vec3(x, y, z)       # Vector with components

# Operations
v3 = v1 + v2           # Addition
dot = v1.dot(v2)       # Dot product
cross = v1.cross(v2)   # Cross product (left-handed)
length = v.length()    # Vector length
v.normalize()          # Normalize in-place
normalized = v.normcopy()  # Return normalized copy

# Static methods
v = vec3.lerp(a, b, t)         # Linear interpolation
angle = vec3.angle(a, b)       # Angle between vectors
```

#### quat - Quaternion

```python
from coordinate_system import quat

# Constructors
q = quat()                     # Identity quaternion
q = quat(w, x, y, z)           # From components
q = quat(angle, axis)          # From angle-axis
q = quat(v1, v2)               # From two vectors

# Operations
q3 = q1 * q2               # Quaternion multiplication
v_rotated = q * v          # Rotate vector
conj = q.conj()            # Conjugate

# Conversion
q.from_eulers(pitch, yaw, roll)  # From Euler angles
```

#### coord3 - 3D Coordinate System

```python
from coordinate_system import coord3

# Constructors
c = coord3()                              # Identity frame
c = coord3(x, y, z)                       # Position only
c = coord3(position, quaternion, scale)   # Full specification

# Factory methods
c = coord3.identity()                    # Identity at origin
c = coord3.from_position(pos)            # At position
c = coord3.from_angle(angle, axis)       # From angle-axis
c = coord3.look_at(eye, target, up)      # Look-at transformation

# Transformations
world_pos = local_pos * coord    # Local to world
local_pos = world_pos / coord    # World to local
c3 = c1 * c2                     # Compose transformations
```

### Differential Geometry Module

```python
from coordinate_system import (
    # Surface classes
    Surface, Sphere, Torus,

    # Intrinsic gradient method (default, more accurate)
    compute_gaussian_curvature,
    compute_mean_curvature,
    compute_riemann_curvature,
    compute_all_curvatures,

    # Classical method (high-order finite differences)
    gaussian_curvature_classical,
    mean_curvature_classical,
    principal_curvatures_classical,

    # Method comparison
    compare_methods,
)

# Create a surface
sphere = Sphere(radius=2.0)
torus = Torus(major_radius=3.0, minor_radius=1.0)

# Compute curvature (intrinsic gradient method)
K = compute_gaussian_curvature(sphere, u=0.5, v=0.5)
H = compute_mean_curvature(sphere, u=0.5, v=0.5)

# Use classical method
K_classical = gaussian_curvature_classical(sphere, u=0.5, v=0.5)

# Compare methods
results = compare_methods(sphere, u=0.5, v=0.5)
print(f"Intrinsic: K={results['intrinsic']['K']:.6f}")
print(f"Classical: K={results['classical']['K']:.6f}")
```

### Quantum Frame Module

```python
from coordinate_system import (
    # Core classes
    QFrame, QuantumState, PathIntegral, QFrameSpectrum,

    # Dirac notation (optional export)
    DiracBra, DiracKet, bra, ket,

    # Spectral transforms
    spectral_transform, inverse_spectral_transform,

    # Constants
    HBAR, GPU_AVAILABLE,
)

# Create quantum frame
qf = QFrame(base_coord=coord3(), q_factor=1.0+0j)

# Fourier transform (phase rotation)
qf_transformed = qf.fourier_transform(theta=np.pi/2)

# 2D spectral transform
import numpy as np
field = np.random.rand(64, 64, 3)  # Random coordinate field
spectrum = QFrame.spectral_transform_2d(field)
reconstructed = QFrame.inverse_spectral_transform_2d(spectrum)

# Path integral
path = PathIntegral()
integral = path.integrate_trajectory([qf1, qf2, qf3])
```

### Visualization Module

```python
from coordinate_system import (
    CoordinateSystemVisualizer,
    CurveVisualizer,
    SurfaceVisualizer,
    visualize_coord_system,
    visualize_curve,
    visualize_surface,
)

# Quick surface visualization with curvature
from coordinate_system import Sphere

sphere = Sphere(radius=1.0)
visualize_surface(
    sphere,
    curvature_type='gaussian',  # or 'mean'
    show_colorbar=True,
    show_normals=False,
    show_frames=True,
    title='Sphere with Gaussian Curvature'
)

# Advanced surface visualization
vis = SurfaceVisualizer(figsize=(12, 10), dpi=120)
vis.draw_surface_curvature(
    sphere,
    curvature_type='gaussian',
    u_range=(0, 2*np.pi),
    v_range=(0, np.pi),
    nu=60, nv=40,
    alpha=0.9,
    show_colorbar=True
)
vis.draw_surface_frames(
    sphere,
    u_range=(0, 2*np.pi),
    v_range=(0, np.pi),
    density=8,
    arrow_length=0.3
)
vis.set_view(elev=30, azim=45)
vis.set_title('Sphere with Frame Field')
vis.show()
```

### Curve Interpolation Module

```python
from coordinate_system import (
    InterpolatedCurve,
    generate_frenet_frames,
    frame_field_spline_c2,
    compute_curvature_profile,
)

# Create C2-continuous interpolated curve
points = [vec3(0, 0, 0), vec3(1, 1, 0), vec3(2, 0, 0), vec3(3, 1, 1)]
curve = InterpolatedCurve(points, method='c2')

# Sample curve
t_values = np.linspace(0, 1, 100)
curve_points = [curve.evaluate(t) for t in t_values]

# Generate smooth frame field
frames = frame_field_spline_c2(points, num_samples=100)

# Compute curvature
curvature = compute_curvature_profile(curve_points)
max_curvature = max(curvature)
```

---

## Coordinate System Type

This library uses a **left-handed coordinate system** for all vector and quaternion operations (as of v3.0.0).

```
         +Y
          |
          |
          |
          +-----> +X
          \
           \
            +Z
```

**Left-Hand Rule:**
- Point your left hand's fingers along the +X axis
- Curl them toward the +Y axis
- Your thumb points along the +Z axis
- Cross product: **X × Y = Z** (common in computer graphics)

---

## Advanced Examples

### Surface Curvature Analysis

```python
from coordinate_system import Torus, compute_all_curvatures, visualize_surface
import numpy as np

# Create a torus
torus = Torus(major_radius=3.0, minor_radius=1.0)

# Compute all curvatures at a point
u, v = np.pi/4, np.pi/3
curvatures = compute_all_curvatures(torus, u, v)

print(f"Gaussian curvature: {curvatures['K']:.6f}")
print(f"Mean curvature: {curvatures['H']:.6f}")
print(f"Principal curvatures: κ1={curvatures['k1']:.6f}, κ2={curvatures['k2']:.6f}")

# Visualize with curvature coloring
visualize_surface(
    torus,
    curvature_type='gaussian',
    u_range=(0, 2*np.pi),
    v_range=(0, 2*np.pi),
    show_colorbar=True,
    title='Torus Gaussian Curvature'
)
```

### Quantum Frame Spectral Analysis

```python
from coordinate_system import QFrame, coord3, vec3
import numpy as np

# Create a coordinate field
coords = []
for i in range(16):
    for j in range(16):
        x, y = i/16.0, j/16.0
        z = np.sin(2*np.pi*x) * np.cos(2*np.pi*y)
        c = coord3(vec3(x, y, z))
        coords.append(c)

coords = np.array(coords).reshape(16, 16)

# Convert to QFrame field
qframes = [[QFrame(c) for c in row] for row in coords]

# Extract position field for spectral analysis
field = np.array([[[qf.base.o.x, qf.base.o.y, qf.base.o.z]
                   for qf in row] for row in qframes])

# Perform spectral transform
spectrum = QFrame.spectral_transform_2d(field)

# Analyze frequency components
power_spectrum = np.abs(spectrum)**2
print(f"Total power: {np.sum(power_spectrum):.6f}")
```

### Camera System with Coordinate Frames

```python
from coordinate_system import vec3, quat, coord3
import math

class Camera:
    def __init__(self, position, target, up=vec3(0, 1, 0)):
        self.frame = coord3.look_at(position, target, up)

    def move_forward(self, distance):
        self.frame.o = self.frame.o + self.frame.uz * distance

    def orbit(self, angle_h, angle_v):
        q_h = quat(angle_h, vec3(0, 1, 0))
        q_v = quat(angle_v, self.frame.ux)
        self.frame.rot(q_h)
        self.frame.rot(q_v)

    def get_view_matrix(self):
        """Get view matrix for rendering"""
        return self.frame

# Usage
cam = Camera(vec3(0, 5, 10), vec3(0, 0, 0))
cam.orbit(0.1, 0)          # Orbit horizontally
cam.move_forward(1.0)      # Move forward
view = cam.get_view_matrix()
```

---

## Performance

Benchmark on Intel i7-10700K @ 3.8GHz:

| Operation | Ops/second | Notes |
|-----------|-----------|-------|
| Vector addition | 5,200,000 | C++ optimized |
| Dot product | 4,800,000 | C++ optimized |
| Cross product | 3,500,000 | C++ optimized |
| Normalize | 2,100,000 | C++ optimized |
| Quaternion rotation | 1,800,000 | C++ optimized |
| Gaussian curvature | 85,000 | Python + NumPy |
| Spectral transform (CPU) | 1,200/sec | 64×64 field |
| Spectral transform (GPU) | 12,000/sec | 64×64 field, CuPy |

---

## Constants

```python
from coordinate_system import ZERO3, UNITX, UNITY, UNITZ, ONE3, ONE4, ONEC

ZERO3  # Zero vector vec3(0, 0, 0)
UNITX  # Unit X vector vec3(1, 0, 0)
UNITY  # Unit Y vector vec3(0, 1, 0)
UNITZ  # Unit Z vector vec3(0, 0, 1)
ONE3   # Unit scale vec3(1, 1, 1)
ONE4   # Identity quaternion quat(1, 0, 0, 0)
ONEC   # World coordinate system coord3()
```

---

## Building from Source

### Prerequisites

- C++17 compatible compiler
- Python 3.7+
- pybind11

### Windows

```bash
# Install Visual Studio 2019+ with C++ tools
pip install pybind11 wheel
python setup.py build
python setup.py bdist_wheel
```

### Linux

```bash
sudo apt install build-essential python3-dev
pip3 install pybind11 wheel
python3 setup.py build
python3 setup.py bdist_wheel
```

### macOS

```bash
xcode-select --install
pip3 install pybind11 wheel
python3 setup.py build
python3 setup.py bdist_wheel
```

---

## System Compatibility

### Operating Systems

| Platform | Status | Notes |
|----------|--------|-------|
| Windows 7+ | ✅ Full Support | Tested on Windows 10/11 |
| Linux | ✅ Full Support | Ubuntu 18.04+, CentOS 7+, Debian 9+ |
| macOS | ✅ Full Support | macOS 10.14 (Mojave) and later |

### Python Versions

- Python 3.7
- Python 3.8
- Python 3.9
- Python 3.10
- Python 3.11
- Python 3.12
- Python 3.13

---

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

---

## License

MIT License - see [LICENSE](LICENSE) file for details

Copyright (c) 2024-2025 PanGuoJun

---

## Author

**PanGuoJun** (romeosoft)

- Email: 18858146@qq.com
- GitHub: [panguojun/Coordinate-System](https://github.com/panguojun/Coordinate-System)

---

## Links

- **PyPI**: https://pypi.org/project/coordinate-system/
- **GitHub**: https://github.com/panguojun/Coordinate-System
- **Mathematical Foundation**: [MATHEMATICAL_FOUNDATION.md](https://github.com/panguojun/Coordinate-System/blob/main/MATHEMATICAL_FOUNDATION.md)
- **Issues**: https://github.com/panguojun/Coordinate-System/issues

---

## Changelog

### Version 6.0.0 (2025-12-03)
- 🔄 **MAJOR REFACTORING**: Unified module architecture
- ✨ **Merged differential_geometry**: Combined curvature.py functionality with dual-method support
- ✨ **Merged qframes**: Integrated qframesnew.py and fourier_spectral.py into unified module
- ✨ **Enhanced visualization**: Added SurfaceVisualizer with curvature coloring
- 📚 **Full English documentation**: Complete internationalization
- ⚡ **Improved API**: Cleaner imports and more intuitive method names
- 🎨 **Better visualization**: Curvature colormaps, frame field rendering

### Version 5.2.2 (2025-12-01)
- ✨ C2-continuous curve interpolation with SQUAD
- ✨ Fourier frames with operator overloading
- 📚 Enhanced documentation

### Version 5.2.1 (2025-12-01)
- ✨ Handedness control at C++ level
- 🔧 Fixed Frenet frame handedness issues
- 📚 Improved global handedness setting

### Version 4.0.0 (2024-11-15)
- ✨ Fourier spectral geometry analysis
- ⚡ GPU acceleration with CuPy
- 🎯 Topological analysis and Berry phase
- 📊 ShapeDNA for shape characterization

### Version 3.0.0 (2024-10-20)
- ⚠️ **BREAKING**: Changed to left-handed coordinate system
- ✅ Complete test suite validation
- 📚 Updated all documentation

### Version 1.2.0 (2024-10-22)
- ✅ Cross-platform support (Windows, Linux, macOS)
- ✅ Performance optimizations
- ✅ Improved API consistency

### Version 1.1.0 (2024-09-08)
- Initial PyPI release
- Core vec3, quat, coord3 classes

---

## Acknowledgments

Built with ❤️ using:
- **C++17** - High-performance core
- **pybind11** - Python-C++ bindings
- **NumPy** - Numerical computations
- **Matplotlib** - Visualization
- **CuPy** - Optional GPU acceleration

---

**Note**: For the latest updates and documentation, visit the [GitHub repository](https://github.com/panguojun/Coordinate-System).
