Metadata-Version: 2.4
Name: coordinate_system
Version: 13.1.1
Summary: Computable coordinate systems for object-level spatial calculus, frame fields, and differential geometry
Author-email: Pan Guojun <18858146@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/panguojun/Coordinate-System
Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
Project-URL: Repository, https://github.com/panguojun/Coordinate-System
Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.14435613
Keywords: 3d,math,vector,quaternion,coordinate-system,computable-coordinate-system,frame-field,differential-geometry,curvature,surface-geometry,spectral-geometry,complex-frame
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: Programming Language :: Python :: 3
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++
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5.0; extra == "plot"
Provides-Extra: scipy
Requires-Dist: scipy>=1.8.0; extra == "scipy"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: matplotlib>=3.5.0; extra == "dev"
Requires-Dist: scipy>=1.8.0; extra == "dev"
Dynamic: license-file

# Coordinate System

`coordinate_system` is a mathematical library for computable coordinate systems,
quaternionic frames, and object-level spatial calculus in Python.

Version 13.1.1 improves the public API documentation and ships runnable examples
for the CCS frame workflow.  The package root is deliberately mathematical: it
exposes coordinate objects, frame-field calculus, curvature operators, spectral
geometry, complex-frame algebra, and curve/surface construction tools.

## Core Idea

A computable coordinate system is a local spatial measuring object:

```text
C = (o, q, s)  or  C = (o, R, D), with E = R D.
```

- `o` is the affine origin.
- `q` or `R` is the local orientation.
- `s` or `D` is the local scale/ruler structure.

The differential datum of a frame field is the logarithmic or relative local
variation of neighboring coordinate objects.  The integral operation is the
ordered composition that reconstructs global geometry from those local changes.

In the CCS frame paper this is the object-level recovery chain:

```text
C = (o, R, D) -> T = [s1 e1, s2 e2] -> g, h, S -> K, H, k1, k2
```

## Installation

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

From source:

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

Source builds require a C++17 compiler and `pybind11`.  Runtime dependency is
kept minimal: `numpy` is required; plotting and SciPy features are optional.

## Public Mathematical Layers

### Core Coordinate Objects

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

p = vec3(1.0, 2.0, 3.0)
q = quat(1.0, 0.0, 0.0, 0.0)
scale = vec3(1.0, 1.0, 1.0)
C = coord3(p, q, scale)
```

Important `vec3` methods: `dot`, `cross`, `len`, `length`, `sqrlen`,
`normalized`, `project`, `reflect`, `distance`, `vec3.lerp`, and `vec3.angle`.

Important `quat` methods: composition with `*`, vector rotation with `q * v` or
`q.rotate(v)`, `normalized`, `inverse`, `to_eulers`, `to_angle_axis`,
`quat.slerp`, `quat.nlerp`, `quat.from_euler`, and `quat.from_axis_angle`.

Important `coord3` fields and methods: `o`/`p`, `ux`, `uy`, `uz`, `s`,
composition `A * B`, relative frame `A / B`, `to_world`, `to_local`, `inverse`,
`Q`, `R`, `VX`, `VY`, `VZ`, `coord3.look_at`, `coord3.from_forward`,
`coord3.lerp`, and `coord3.slerp`.

### CCS Surface Geometry

```python
import math
from coordinate_system import Sphere, compute_ccs_geometry_package

sphere = Sphere(radius=2.0)
pkg = compute_ccs_geometry_package(sphere, math.pi / 4.0, math.pi / 3.0)

print(pkg.K)       # Gaussian curvature
print(pkg.H)       # Mean curvature
print(pkg.g)       # First fundamental form
print(pkg.h)       # Second fundamental form
print(pkg.center_frame)
```

`compute_ccs_geometry_package` returns a `CCSGeometryPackage` with:

- `center_frame`: surface-adapted `coord3`
- `G_u`, `G_v`: finite relative CCS variation objects
- `g`: first fundamental form
- `h`: second fundamental form
- `S`: shape operator
- `K`, `H`, `k1`, `k2`: curvature invariants
- `normal`: unit normal as a NumPy array
- `riemann_1212`: Riemann component
- `as_dict()`: dictionary view

Related curvature functions:

```python
from coordinate_system import (
    compute_gaussian_curvature,
    compute_mean_curvature,
    compute_riemann_curvature,
    compute_all_curvatures,
    compute_intrinsic_gradient,
    compute_connection_matrices,
)
```

For custom surfaces, subclass `Surface` and implement `position(u, v)`. For
better speed and accuracy, optionally add `derivs(u, v)` returning
`(r_u, r_v, r_uu, r_uv, r_vv)`.

The package keeps the theorem chain explicit:

```text
coord frame -> finite relative variation -> metric/shape data -> curvature invariants
```

### Convenience CCS Wrapper

```python
import math
from coordinate_system import CCS, Sphere

ccs = CCS(step_size=1e-4)
sphere = Sphere(radius=2.0)

print(ccs.gaussian(sphere, math.pi / 4.0, math.pi / 3.0))
print(ccs.mean(sphere, math.pi / 4.0, math.pi / 3.0))
```

The wrapper methods are `geometry_package`, `gaussian`, `mean`, `riemann`,
`connection_matrices`, and `curvature_tensor`.

### Custom Surface Example

```python
from coordinate_system import Surface, compute_ccs_geometry_package, vec3

class Paraboloid(Surface):
    def position(self, u, v):
        return vec3(u, v, 0.25 * (u*u + v*v))

    def derivs(self, u, v):
        return (
            vec3(1, 0, 0.5*u),
            vec3(0, 1, 0.5*v),
            vec3(0, 0, 0.5),
            vec3(0, 0, 0),
            vec3(0, 0, 0.5),
        )

pkg = compute_ccs_geometry_package(Paraboloid(), 0.4, -0.2)
print(pkg.K, pkg.H)
```



### Helicity-Phase Utilities

The package now includes a small mathematical module for CFLH-style validation:

```python
from coordinate_system.helicity_phase import (
    cumulative_pose_exposure,
    integrate_helicity_phase,
    integrate_compact_branch,
)
```

These helpers are generic. They turn a monotone CCS frame exposure into a
phase trajectory, branch labels, and compact finite-capacity closure diagnostics.

### Curve and Surface Construction

```python
import math
from coordinate_system import AnalyticSphere, interpolate_surface_coords

surface = AnalyticSphere(radius=1.0)
frames = interpolate_surface_coords(
    surface,
    [(math.pi / 3.0, 0.0), (math.pi / 3.0, math.pi / 2.0)],
    samples=16,
)

points = [item.frame.o for item in frames]
```

NURBS entry points include `NURBSCurve`, `NURBSCurve2D`, `NURBSSurface`,
`make_nurbs_curve`, `make_nurbs_surface`, `sample_nurbs_frame_curve`,
`nurbs_arc_length`, `nurbs_curvature_profile`, and NURBS intersection helpers.

CoordScript entry points include `parse_coordscript`, `eval_coordscript`, and
`eval_coordscript_file`.

These APIs are mathematical construction tools.  Downstream CAD, rendering, or
simulation systems can consume the resulting coord frames, but those application
layers are not part of the package root.

### Spectral and Complex Frames

```python
from coordinate_system import ComplexFrame, GaugeConnection, FourierFrame

U = ComplexFrame()
A = GaugeConnection()
```

The complex-frame layer is kept as a mathematical utility for unitary frames,
connections, field-strength-like algebra, and spectral constructions.  It should
not be read as a validated physical model by itself.

## API Boundary in 13.0.0

Removed from the public package root:

- CFUT wrapper APIs
- Lambda wrapper APIs
- topological physics application functions
- research registry helpers
- report-generation scripts
- dark-matter, dynamic-stall, and validation application examples

Kept in the mathematical package root:

- `vec3`, `vec2`, `quat`, `coord3`
- `CCS`, `Surface`, `Sphere`, `Torus`
- metric, intrinsic-gradient, curvature, and CCS geometry package APIs
- spectral geometry utilities
- complex-frame algebra utilities
- curve interpolation, curve intersection, and analytic surface coord tools
- NURBS and CoordScript helpers

## Development Smoke Test

```bash
python -c "import coordinate_system as cs; print(cs.__version__, cs.Sphere(2).theoretical_gaussian_curvature)"
python -m unittest discover -s test
```

## License

MIT License. Copyright (c) 2024-2026 Pan Guojun.

DOI: https://doi.org/10.5281/zenodo.14435613
