coordinate-system 2.3.3

High-performance 3D coordinate system library with C++ optimized differential geometry and high-precision discrete curvature computation (Gaussian/Mean/Principal curvatures)

Coordinate System Library

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

Author: PanGuoJun Version: 2.2.0 License: MIT

🆕 What's New in v2.2.0

Major Feature Release: Discrete Differential Geometry!

• ✨ Metric Tensor Computation - First fundamental form on surfaces
• ✨ Connection Operators - Discrete frame derivatives (intrinsic gradients)
• ✨ Curvature Tensors - Complete R_uv computation with Lie derivatives
• ✨ Gaussian Curvature - High-accuracy discrete curvature (2.22% error on spheres!)
• ✨ Surface Classes - Sphere, Torus, and extensible Surface base class

Perfect for computational geometry, geometric analysis, and discrete differential geometry research!

---

Features

Core Classes

• vec3 - 3D vector with comprehensive operations
• quat - Quaternion for 3D rotations
• coord3 - Complete 3D coordinate system (position, rotation, scale)

Operations

• Vector arithmetic (+, -, *, /)
• Dot product, cross product
• Vector projection, reflection
• Linear interpolation (lerp)
• Spherical linear interpolation (slerp)
• Coordinate system transformations
• Euler angle conversion

Performance

• Written in optimized C++17
• Python bindings via pybind11
• Over 1,000,000 operations per second

Platform Support

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

---

🆕 Differential Geometry (NEW in v2.2.0)

Surface Representation

from coordinate_system import Sphere, Torus, Surface

# Create a sphere
sphere = Sphere(radius=2.0)

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

# Or define your own surface by subclassing Surface
class MySurface(Surface):
    def position(self, u, v):
        # Return vec3(x, y, z) for parameters (u, v)
        pass

Metric Tensor (First Fundamental Form)

from coordinate_system import compute_metric
import math

# Compute metric tensor at a point
g = compute_metric(sphere, u=math.pi/4, v=math.pi/3)

print(f"E = {g.E:.6f}")   # u-direction metric
print(f"F = {g.F:.6f}")   # cross term (0 if orthogonal)
print(f"G = {g.G:.6f}")   # v-direction metric
print(f"det(g) = {g.det:.6f}")
print(f"Metric correction = {g.correction_factor():.6f}")

Connection Operator (Intrinsic Gradient)

from coordinate_system import compute_connection

# Compute connection operator (frame derivative)
G_u = compute_connection(sphere, u=math.pi/4, v=math.pi/3, direction='u')
G_v = compute_connection(sphere, u=math.pi/4, v=math.pi/3, direction='v')

print(f"G_u norm: {G_u.norm():.8f}")
print(f"G_v norm: {G_v.norm():.8f}")

Aliases available:

• compute_frame_derivative (standard mathematical term)
• compute_intrinsic_gradient (intuitive name)
• compute_geometric_gradient (alternative)

Curvature Tensor

from coordinate_system import compute_curvature_tensor

# Compute complete curvature tensor R_uv
R_uv = compute_curvature_tensor(
    sphere,
    u=math.pi/4,
    v=math.pi/3,
    use_lie_derivative=True  # CRITICAL for accuracy!
)

print(f"Curvature tensor norm: {R_uv.norm():.8f}")

# R_uv is a 3×3 coord3 object with structure:
# [[R_11, R_12, R_13],   ← Tangent-tangent (intrinsic)
#  [R_21, R_22, R_23],   ← Tangent-normal (second fundamental form)
#  [R_31, R_32, R_33]]   ← Normal-normal (extrinsic)

Gaussian Curvature (Quickest Method)

from coordinate_system import Sphere, compute_gaussian_curvature
import math

# One-line curvature computation!
sphere = Sphere(radius=2.0)
K = compute_gaussian_curvature(sphere, u=math.pi/4, v=math.pi/3)

print(f"Gaussian curvature K = {K:.6f}")
# Expected: K = 1/R² = 0.25 for a sphere

# Theoretical value
K_theory = 1.0 / (2.0 ** 2)
error = abs(K - K_theory) / K_theory * 100
print(f"Relative error: {error:.2f}%")  # Typically < 3% !

Accuracy Comparison

On a sphere with radius R=2:

Method	Lie Derivative	Accuracy	Improvement
Without correction	❌	54.32% error	-
With scale correction	✓	17.09% error	3.2×
Optimal (scale + metric + Lie)	✓	2.22% error	24× 🎉

The Lie derivative term is CRITICAL! It improves accuracy by 24× on spheres.

Key Parameters

# For constant curvature surfaces (spheres):
K = compute_gaussian_curvature(
    surface,
    u, v,
    scale_factor=2.0,           # Optimal for spheres
    use_metric_correction=True,  # Essential!
    use_lie_derivative=True      # Critical for accuracy!
)

# These are the default values, optimized for best accuracy

Complete Example

See examples/curvature_computation.py for comprehensive demonstrations, or examples/quickstart.py for the simplest possible usage.

# examples/quickstart.py
import math
from coordinate_system import Sphere, compute_gaussian_curvature

# Step 1: Create a sphere
sphere = Sphere(radius=2.0)

# Step 2: Choose a point
u, v = math.pi/4, math.pi/3

# Step 3: Compute curvature (one line!)
K = compute_gaussian_curvature(sphere, u, v)

# Step 4: Compare with theory
K_theory = 1.0 / (2.0 ** 2)  # K = 1/R²
print(f"Computed: K = {K:.6f}")
print(f"Theory:   K = {K_theory:.6f}")
print(f"Error: {abs(K-K_theory)/K_theory*100:.2f}%")

---

📚 Documentation

Mathematical Foundation

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

📖 Mathematical Foundation of Coordinate Systems

This guide covers:

• Vector mathematics (dot product, cross product, projections)
• Quaternion theory and applications
• Coordinate system transformations
• Euler angles and gimbal lock
• Interpolation methods (LERP, SLERP, NLERP)
• Practical applications in graphics, physics, and robotics

---

Installation

From PyPI (Recommended)

pip install coordinate-system

From Source

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

---

Quick Start

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
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

# Interpolation
lerped = vec3.lerp(v1, v2, 0.5)  # Linear interpolation

---

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

---

Coordinate System Type

This library uses a left-handed coordinate system for all vector and quaternion operations.

      +Y
       |
       |
       |
       +-----> +X
      /
     /
   +Z

---

API Reference

vec3 - 3D Vector

Constructors

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

Properties

v.x  # X component
v.y  # Y component
v.z  # Z component

Arithmetic Operations

v3 = v1 + v2           # Addition
v3 = v1 - v2           # Subtraction
v3 = v1 * scalar       # Scalar multiplication
v3 = scalar * v1       # Reverse scalar multiplication
v3 = v1 / scalar       # Scalar division
v3 = v1 * v2           # Component-wise multiplication

Vector Operations

dot = v1.dot(v2)       # Dot product (float)
cross = v1.cross(v2)   # Cross product (vec3)
length = v.length()    # Vector length
v.normalize()          # Normalize in-place
normalized = v.normcopy()  # Return normalized copy

Additional Methods

v.lenxy()              # Length in XY plane
v.sqrlen()             # Squared length
v.abslen()             # Sum of absolute components
v.isINF()              # Check for infinity
v.flipX()              # Flip X component
v.flipY()              # Flip Y component
v.flipZ()              # Flip Z component

Static Methods

v = vec3.min3(a, b, c)         # Component-wise minimum
v = vec3.max3(a, b, c)         # Component-wise maximum
v = vec3.rnd()                 # Random vector
v = vec3.lerp(a, b, t)         # Linear interpolation
angle = vec3.angle(a, b)       # Angle between vectors

---

quat - Quaternion

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

Properties

q.w, q.x, q.y, q.z  # Quaternion components

Operations

q3 = q1 + q2               # Addition
q3 = q1 * q2               # Multiplication (composition)
v_rotated = q * v          # Rotate vector
q3 = q1 / q2               # Division

Methods

q.normalize()              # Normalize in-place
normalized = q.normalized()  # Return normalized copy
conj = q.conj()            # Conjugate
length = q.length()        # Length
dot = q1.dot(q2)           # Dot product
angle = q1.angle_to(q2)    # Angle to another quaternion

Conversion

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

# From vectors
q.fromvectors(v1, v2)

# Advanced
q_exp = q.exp()            # Exponential
q_log = q.log()            # Logarithm

---

coord3 - 3D Coordinate System

A coord3 represents a complete 3D coordinate frame with:

• Position (o): Origin in 3D space
• Rotation (ux, uy, uz): Three orthonormal axes
• Scale (s): Scale factors for each axis

Constructors

c = coord3()                              # Identity frame
c = coord3(x, y, z)                       # Position only
c = coord3(x, y, z, pitch, yaw, roll)     # Position + rotation (Euler)
c = coord3(x, y, z, qw, qx, qy, qz)       # Position + rotation (quaternion)
c = coord3(position)                      # From vec3
c = coord3(ux, uy, uz)                    # From three axes
c = coord3(angle, axis)                   # From angle-axis rotation
c = coord3(quaternion)                    # From quaternion
c = coord3(position, quaternion, scale)   # Full specification

Properties

c.o          # Origin (vec3)
c.ux, c.uy, c.uz  # Axis vectors (vec3)
c.s          # Scale (vec3)

Static Factory Methods

c = coord3.from_axes(ux, uy, uz)         # From three axes
c = coord3.from_angle(angle, axis)       # From angle-axis

Transformations

# Transform point from local to world
world_pos = local_pos * coord

# Transform point from world to local
local_pos = world_pos / coord

# Combine coordinate systems
c3 = c1 * c2

Operations

c3 = c1 + c2           # Add (translate)
c3 = c1 - c2           # Subtract
c3 = c1 * c2           # Multiply (compose transformations)
c3 = c1 / c2           # Divide
equal = c1 == c2       # Equality check

Methods

pos = c.pos()          # Get position vector
vec = c.tovec()        # Convert to vector
c.rot(angle, axis)     # Rotate by angle-axis
c.rot(quaternion)      # Rotate by quaternion
equal = c1.equal_dirs(c2)  # Check if axes are equal
hash_val = c.hash()    # Hash value
serial = c.serialise() # Serialize to string
c.dump()               # Print debug info

---

Usage Examples

Vector Mathematics

from coordinate_system import vec3

# Create vectors
v1 = vec3(1, 0, 0)
v2 = vec3(0, 1, 0)

# Basic operations
v3 = v1 + v2                    # vec3(1, 1, 0)
v4 = v1 * 5                     # vec3(5, 0, 0)

# Dot and cross products
dot = v1.dot(v2)                # 0.0 (perpendicular)
cross = v1.cross(v2)            # vec3(0, 0, 1) in left-handed system

# Length and normalization
length = v1.length()            # 1.0
v_normalized = v1.normcopy()   # Unit vector

# Linear interpolation
v_mid = vec3.lerp(v1, v2, 0.5)  # vec3(0.5, 0.5, 0)

Quaternion Rotations

from coordinate_system import vec3, quat

# Create quaternion from angle-axis
import math
axis = vec3(0, 0, 1)           # Z axis
angle = math.pi / 2             # 90 degrees
q = quat(angle, axis)

# Rotate vector
v = vec3(1, 0, 0)
rotated = q * v                 # Approximately vec3(0, 1, 0)

# Create quaternion from two vectors
v_from = vec3(1, 0, 0)
v_to = vec3(0, 1, 0)
q = quat(v_from, v_to)

# Quaternion composition
q1 = quat(math.pi/4, vec3(0, 0, 1))  # 45° around Z
q2 = quat(math.pi/4, vec3(0, 1, 0))  # 45° around Y
combined = q1 * q2                    # Combined rotation

# Euler angles
q.from_eulers(pitch=0.1, yaw=0.2, roll=0.3)

Coordinate System Transformations

from coordinate_system import vec3, quat, coord3
import math

# Create a coordinate system at position (5, 10, 15)
frame = coord3(5, 10, 15)

# Create with rotation
q = quat(math.pi/4, vec3(0, 0, 1))  # 45° rotation
frame = coord3(vec3(5, 10, 15), q, vec3(1, 1, 1))

# Transform points between coordinate systems
world_point = vec3(10, 0, 0)
local_point = world_point / frame   # World to local
back_to_world = local_point * frame  # Local to world

# Hierarchical transformations
parent = coord3(0, 5, 0)
child = coord3(3, 0, 0)
child_in_world = child * parent

# Create look-at transformation (custom implementation needed)
def look_at(eye, target, up=vec3(0, 1, 0)):
    forward = (target - eye).normcopy()
    right = up.cross(forward).normcopy()
    up_corrected = forward.cross(right)
    return coord3.from_axes(right, up_corrected, forward)

camera = look_at(vec3(10, 10, 10), vec3(0, 0, 0))

Practical Applications

Camera System

from coordinate_system import vec3, quat, coord3
import math

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

    def create_look_at(self, eye, target, up):
        forward = (target - eye).normcopy()
        right = up.cross(forward).normcopy()
        up_corrected = forward.cross(right)

        c = coord3()
        c.o = eye
        c.ux = right
        c.uy = up_corrected
        c.uz = forward
        return c

    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)

# 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

Physics Simulation

from coordinate_system import vec3, quat, coord3

class RigidBody:
    def __init__(self, position=vec3(0, 0, 0)):
        self.frame = coord3(position)
        self.velocity = vec3(0, 0, 0)
        self.angular_velocity = vec3(0, 0, 0)

    def apply_force(self, force, dt):
        self.velocity = self.velocity + force * dt

    def update(self, dt):
        # Update position
        self.frame.o = self.frame.o + self.velocity * dt

        # Update rotation
        if self.angular_velocity.length() > 0:
            angle = self.angular_velocity.length() * dt
            axis = self.angular_velocity.normcopy()
            q = quat(angle, axis)
            self.frame.rot(q)

# Usage
body = RigidBody(vec3(0, 10, 0))
gravity = vec3(0, -9.8, 0)

dt = 1.0 / 60.0  # 60 FPS
for _ in range(100):
    body.apply_force(gravity, dt)
    body.update(dt)

---

Advanced Features

Interpolation

The package provides helper functions for interpolation:

from coordinate_system import lerp

# Linear interpolation
v1 = vec3(0, 0, 0)
v2 = vec3(10, 10, 10)
v_mid = lerp(v1, v2, 0.5)  # vec3(5, 5, 5)

For spherical linear interpolation (slerp), use quaternions:

q1 = quat()  # Identity
q2 = quat(1.57, vec3(0, 0, 1))  # 90° rotation

# Manual slerp implementation or use quaternion methods
# (depends on availability in your binding)

Constants

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

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

Linux

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

macOS

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

---

Performance

Benchmark on Intel i7-10700K @ 3.8GHz:

Operation	Ops/second
Vector addition	5,200,000
Dot product	4,800,000
Cross product	3,500,000
Normalize	2,100,000
Quaternion rotation	1,800,000

---

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 file for details

Copyright (c) 2024-2025 PanGuoJun

---

Author

PanGuoJun (romeosoft)

• Email: [e-mail]
• GitHub: panguojun/Coordinate-System

---

Links

• PyPI: https://pypi.org/project/coordinate-system/
• GitHub: https://github.com/panguojun/Coordinate-System
• Mathematical Foundation: MATHEMATICAL_FOUNDATION.md
• Issues: https://github.com/panguojun/Coordinate-System/issues

---

Changelog

Version 1.2.0 (2025-10-22)

• ✅ Cross-platform support (Windows, Linux, macOS)
• ✅ Updated documentation
• ✅ Improved API consistency
• ✅ Added more usage examples
• ✅ Performance optimizations

Version 1.1.0 (2024-09-08)

• Initial PyPI release
• Windows support
• Core vec3, quat, coord3 classes

---

Acknowledgments

Built with ❤️ using:

• C++17
• pybind11
• Python

---

Note: For the latest updates and documentation, visit the GitHub repository.