coordinate-system 5.2.2__cp313-cp313-win_amd64.whl → 6.0.1__cp313-cp313-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- coordinate_system/__init__.py +120 -145
- coordinate_system/differential_geometry.py +618 -298
- coordinate_system/fourier_spectral.py +115 -729
- coordinate_system/frames.py +1571 -0
- coordinate_system/qframes.py +747 -630
- coordinate_system/visualization.py +695 -292
- coordinate_system-6.0.1.dist-info/METADATA +721 -0
- coordinate_system-6.0.1.dist-info/RECORD +15 -0
- coordinate_system-5.2.2.dist-info/METADATA +0 -807
- coordinate_system-5.2.2.dist-info/RECORD +0 -14
- {coordinate_system-5.2.2.dist-info → coordinate_system-6.0.1.dist-info}/LICENSE +0 -0
- {coordinate_system-5.2.2.dist-info → coordinate_system-6.0.1.dist-info}/WHEEL +0 -0
- {coordinate_system-5.2.2.dist-info → coordinate_system-6.0.1.dist-info}/top_level.txt +0 -0
|
@@ -1,807 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.1
|
|
2
|
-
Name: coordinate_system
|
|
3
|
-
Version: 5.2.2
|
|
4
|
-
Summary: High-performance 3D coordinate system with C2-continuous curve interpolation, Fourier frames with operator overloading, and advanced 3D visualization
|
|
5
|
-
Home-page: https://github.com/panguojun/Coordinate-System
|
|
6
|
-
Author: PanGuoJun
|
|
7
|
-
Author-email: 18858146@qq.com
|
|
8
|
-
License: MIT
|
|
9
|
-
Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
|
|
10
|
-
Project-URL: Source, https://github.com/panguojun/Coordinate-System
|
|
11
|
-
Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
|
|
12
|
-
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
|
|
13
|
-
Platform: Windows
|
|
14
|
-
Platform: Linux
|
|
15
|
-
Platform: macOS
|
|
16
|
-
Platform: Android
|
|
17
|
-
Platform: iOS
|
|
18
|
-
Classifier: Development Status :: 5 - Production/Stable
|
|
19
|
-
Classifier: Intended Audience :: Developers
|
|
20
|
-
Classifier: Intended Audience :: Science/Research
|
|
21
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
-
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
23
|
-
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
|
|
24
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
25
|
-
Classifier: Programming Language :: Python :: 3
|
|
26
|
-
Classifier: Programming Language :: Python :: 3.7
|
|
27
|
-
Classifier: Programming Language :: Python :: 3.8
|
|
28
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
29
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
30
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
31
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
32
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
33
|
-
Classifier: Programming Language :: C++
|
|
34
|
-
Classifier: Operating System :: Microsoft :: Windows
|
|
35
|
-
Classifier: Operating System :: POSIX :: Linux
|
|
36
|
-
Classifier: Operating System :: MacOS
|
|
37
|
-
Requires-Python: >=3.7
|
|
38
|
-
Description-Content-Type: text/markdown
|
|
39
|
-
License-File: LICENSE
|
|
40
|
-
Requires-Dist: numpy>=1.19.0
|
|
41
|
-
Requires-Dist: matplotlib>=3.3.0
|
|
42
|
-
|
|
43
|
-
# Coordinate System Library
|
|
44
|
-
|
|
45
|
-
**High-performance 3D coordinate system and differential geometry library for Python**
|
|
46
|
-
|
|
47
|
-
[](https://pypi.org/project/coordinate-system/)
|
|
48
|
-
[](https://pypi.org/project/coordinate-system/)
|
|
49
|
-
[](https://pypi.org/project/coordinate-system/)
|
|
50
|
-
[](LICENSE)
|
|
51
|
-
|
|
52
|
-
**Author:** PanGuoJun
|
|
53
|
-
**Version:** 5.2.1
|
|
54
|
-
**License:** MIT
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
---
|
|
58
|
-
|
|
59
|
-
## What's New in v5.2.1 (2025-12-01)
|
|
60
|
-
|
|
61
|
-
### Fourier Frames with Operator Overloading
|
|
62
|
-
|
|
63
|
-
**New Module: `fourier_frames`** - Elegant quantum coordinate transformations
|
|
64
|
-
|
|
65
|
-
- **Operator Overloading Support**: Intuitive syntax for Fourier transforms
|
|
66
|
-
- `F_p @ psi` - Matrix multiplication operator
|
|
67
|
-
- `F_p * psi` - Multiplication operator
|
|
68
|
-
- `psi | F_p` - Bra-ket notation
|
|
69
|
-
- `~F_x` - Dual frame operator
|
|
70
|
-
- **Quantum State Representation**: `QuantumState` and `StateVector` classes
|
|
71
|
-
- **Heisenberg Uncertainty**: Built-in uncertainty principle computations
|
|
72
|
-
- **Position <-> Momentum Transforms**: Seamless coordinate basis transformations
|
|
73
|
-
|
|
74
|
-
### C2-Continuous Curve Interpolation
|
|
75
|
-
|
|
76
|
-
**Enhanced Module: `curve_interpolation`** - Second-order smooth curves
|
|
77
|
-
|
|
78
|
-
- **C2-Continuity**: Catmull-Rom spline for position interpolation
|
|
79
|
-
- **SQUAD Interpolation**: Spherical Quadrangle for smooth quaternion interpolation
|
|
80
|
-
- **13x Smoother**: Reduced maximum curvature from 13.93 to 1.05
|
|
81
|
-
|
|
82
|
-
### Advanced 3D Visualization
|
|
83
|
-
|
|
84
|
-
**New Module: `visualization`** - Professional curve and frame rendering
|
|
85
|
-
|
|
86
|
-
- **RGB Frenet Frames**: Red=Tangent, Green=Normal, Blue=Binormal
|
|
87
|
-
- **3D Curve Rendering**: High-quality visualization with matplotlib
|
|
88
|
-
- **Export Support**: Save PNG/PDF outputs
|
|
89
|
-
|
|
90
|
-
### Documentation
|
|
91
|
-
|
|
92
|
-
- [Curve Interpolation Guide](CURVE_INTERPOLATION_README.md)
|
|
93
|
-
- [C2 Interpolation Guide](C2_INTERPOLATION_GUIDE.md)
|
|
94
|
-
- Full English documentation for global distribution
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
### v5.2.1 (2025-12-01) - Handedness Control
|
|
99
|
-
- ✨ **New**: C++ level handedness control (`set_handedness('left'/'right')`)
|
|
100
|
-
- 🔧 **Fixed**: Frenet frames now respect coordinate system handedness
|
|
101
|
-
- 📚 **Improved**: Global handedness setting for consistent behavior
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
## 🆕 What's New in v4.0.0
|
|
105
|
-
|
|
106
|
-
### 🎯 Fourier Spectral Geometry Analysis
|
|
107
|
-
|
|
108
|
-
**New Module: `fourier_spectral`** - Advanced spectral analysis for coordinate fields
|
|
109
|
-
|
|
110
|
-
- **Spectral Geometry Framework**: Unified analysis of geometric structures in frequency domain
|
|
111
|
-
- **GPU Acceleration**: CuPy-based Fourier transforms for large-scale computations
|
|
112
|
-
- **Topological Analysis**: Berry phase and topological invariant calculations
|
|
113
|
-
- **ShapeDNA**: Radial spectrum averaging for shape characterization
|
|
114
|
-
- **Batch Processing**: Efficient batch coordinate transformations
|
|
115
|
-
|
|
116
|
-
### Key Features:
|
|
117
|
-
- **FrameFieldSpectrum**: Structured representation of coordinate field spectra
|
|
118
|
-
- **GPU Fourier Transforms**: 5-10x speedup for large grids
|
|
119
|
-
- **Spectral Curvature**: Intrinsic geometry analysis in frequency domain
|
|
120
|
-
- **Topological Classification**: Automatic detection of geometric types (sphere, torus, plane, saddle)
|
|
121
|
-
|
|
122
|
-
## 🆕 What's New in v3.0.0
|
|
123
|
-
|
|
124
|
-
**Critical Coordinate System Update - Left-Hand System!**
|
|
125
|
-
|
|
126
|
-
- ⚠️ **BREAKING CHANGE: Left-Hand Coordinate System** - Unified all operations to standard left-hand coordinate system
|
|
127
|
-
- `vec3.cross()` now uses left-hand rule (common in computer graphics)
|
|
128
|
-
- Quaternion rotations follow left-hand convention (clockwise is positive)
|
|
129
|
-
- `coord3.look_at()` and `coord3.from_forward()` updated accordingly
|
|
130
|
-
- **Migration Guide:** See [HANDEDNESS_CHANGE.md](HANDEDNESS_CHANGE.md) for details
|
|
131
|
-
- `cross_right()` method retained for backward compatibility
|
|
132
|
-
- ✅ **Verified Correctness** - Complete test suite validates left-hand system behavior
|
|
133
|
-
- 📚 **Updated Documentation** - All examples and documentation reflect new coordinate system
|
|
134
|
-
- 🎯 **Enhanced Clarity** - Comments and docstrings clarified throughout
|
|
135
|
-
|
|
136
|
-
**Why This Change:**
|
|
137
|
-
1. Graphics Standard: Left-hand system is common in computer graphics and DirectX
|
|
138
|
-
2. Better Interoperability: Compatible with DirectX, Unity, and many game engines
|
|
139
|
-
3. Improved Readability: Standard cross product formulas match graphics pipeline definitions
|
|
140
|
-
|
|
141
|
-
Perfect for computer graphics, game development, and 3D visualization applications!
|
|
142
|
-
|
|
143
|
-
---
|
|
144
|
-
|
|
145
|
-
## Features
|
|
146
|
-
|
|
147
|
-
### Core Classes
|
|
148
|
-
|
|
149
|
-
- **vec3** - 3D vector with comprehensive operations
|
|
150
|
-
- **quat** - Quaternion for 3D rotations
|
|
151
|
-
- **coord3** - Complete 3D coordinate system (position, rotation, scale)
|
|
152
|
-
|
|
153
|
-
### Operations
|
|
154
|
-
|
|
155
|
-
- Vector arithmetic (+, -, *, /)
|
|
156
|
-
- Dot product, cross product
|
|
157
|
-
- Vector projection, reflection
|
|
158
|
-
- Linear interpolation (lerp)
|
|
159
|
-
- Spherical linear interpolation (slerp)
|
|
160
|
-
- Coordinate system transformations
|
|
161
|
-
- Euler angle conversion
|
|
162
|
-
|
|
163
|
-
### Performance
|
|
164
|
-
|
|
165
|
-
- Written in optimized C++17
|
|
166
|
-
- Python bindings via pybind11
|
|
167
|
-
- Over 1,000,000 operations per second
|
|
168
|
-
|
|
169
|
-
### Platform Support
|
|
170
|
-
|
|
171
|
-
- ✅ Windows (7, 10, 11)
|
|
172
|
-
- ✅ Linux (Ubuntu, Debian, CentOS, etc.)
|
|
173
|
-
- ✅ macOS (10.14+)
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
## 📚 Documentation
|
|
179
|
-
|
|
180
|
-
### Mathematical Foundation
|
|
181
|
-
|
|
182
|
-
For a comprehensive understanding of the mathematical principles behind coordinate systems, vectors, quaternions, and transformations, see our detailed mathematical guide:
|
|
183
|
-
|
|
184
|
-
**[📖 Mathematical Foundation of Coordinate Systems](https://github.com/panguojun/Coordinate-System)**
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
## Installation
|
|
190
|
-
|
|
191
|
-
### From PyPI (Recommended)
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
pip install coordinate-system
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
### From Source
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
git clone https://github.com/panguojun/Coordinate-System.git
|
|
201
|
-
cd Coordinate-System
|
|
202
|
-
pip install .
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
---
|
|
206
|
-
|
|
207
|
-
## Quick Start
|
|
208
|
-
|
|
209
|
-
```python
|
|
210
|
-
from coordinate_system import vec3, quat, coord3
|
|
211
|
-
|
|
212
|
-
# Create vectors
|
|
213
|
-
v1 = vec3(1, 2, 3)
|
|
214
|
-
v2 = vec3(4, 5, 6)
|
|
215
|
-
|
|
216
|
-
# Vector operations
|
|
217
|
-
v3 = v1 + v2 # Addition: vec3(5, 7, 9)
|
|
218
|
-
dot = v1.dot(v2) # Dot product: 32.0
|
|
219
|
-
cross = v1.cross(v2) # Cross product
|
|
220
|
-
length = v1.length() # Length: 3.742
|
|
221
|
-
normalized = v1.normcopy() # Unit vector
|
|
222
|
-
|
|
223
|
-
# Quaternion rotation
|
|
224
|
-
axis = vec3(0, 0, 1) # Z axis
|
|
225
|
-
q = quat(1.5708, axis) # 90 degrees rotation
|
|
226
|
-
rotated = q * v1 # Rotate v1
|
|
227
|
-
|
|
228
|
-
# Coordinate systems
|
|
229
|
-
frame = coord3.from_angle(1.57, vec3(0, 0, 1)) # Frame rotated 90°
|
|
230
|
-
world_pos = v1 * frame # Transform to world space
|
|
231
|
-
local_pos = world_pos / frame # Transform back to local
|
|
232
|
-
|
|
233
|
-
# Interpolation
|
|
234
|
-
lerped = vec3.lerp(v1, v2, 0.5) # Linear interpolation
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
---
|
|
238
|
-
|
|
239
|
-
## System Compatibility
|
|
240
|
-
|
|
241
|
-
### Operating Systems
|
|
242
|
-
|
|
243
|
-
| Platform | Status | Notes |
|
|
244
|
-
|----------|--------|-------|
|
|
245
|
-
| Windows 7+ | ✅ Full Support | Tested on Windows 10/11 |
|
|
246
|
-
| Linux | ✅ Full Support | Ubuntu 18.04+, CentOS 7+, Debian 9+ |
|
|
247
|
-
| macOS | ✅ Full Support | macOS 10.14 (Mojave) and later |
|
|
248
|
-
|
|
249
|
-
### Python Versions
|
|
250
|
-
|
|
251
|
-
- Python 3.7
|
|
252
|
-
- Python 3.8
|
|
253
|
-
- Python 3.9
|
|
254
|
-
- Python 3.10
|
|
255
|
-
- Python 3.11
|
|
256
|
-
- Python 3.12
|
|
257
|
-
- Python 3.13
|
|
258
|
-
|
|
259
|
-
---
|
|
260
|
-
|
|
261
|
-
## Coordinate System Type
|
|
262
|
-
|
|
263
|
-
This library uses a **left-handed coordinate system** for all vector and quaternion operations (as of v3.0.0).
|
|
264
|
-
|
|
265
|
-
```
|
|
266
|
-
+Y
|
|
267
|
-
|
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
+-----> +X
|
|
271
|
-
\
|
|
272
|
-
\
|
|
273
|
-
+Z
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
**Left-Hand Rule:**
|
|
277
|
-
- Point your left hand's fingers along the +X axis
|
|
278
|
-
- Curl them toward the +Y axis
|
|
279
|
-
- Your thumb points along the +Z axis
|
|
280
|
-
- Cross product: **X × Y = Z** (common in computer graphics)
|
|
281
|
-
|
|
282
|
-
**Migration from v2.x:** If your code relied on the previous right-handed system, see [HANDEDNESS_CHANGE.md](HANDEDNESS_CHANGE.md) for migration instructions.
|
|
283
|
-
|
|
284
|
-
---
|
|
285
|
-
|
|
286
|
-
## API Reference
|
|
287
|
-
|
|
288
|
-
### vec3 - 3D Vector
|
|
289
|
-
|
|
290
|
-
#### Constructors
|
|
291
|
-
|
|
292
|
-
```python
|
|
293
|
-
v = vec3() # Zero vector (0, 0, 0)
|
|
294
|
-
v = vec3(x, y, z) # Vector with components
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
#### Properties
|
|
298
|
-
|
|
299
|
-
```python
|
|
300
|
-
v.x # X component
|
|
301
|
-
v.y # Y component
|
|
302
|
-
v.z # Z component
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
#### Arithmetic Operations
|
|
306
|
-
|
|
307
|
-
```python
|
|
308
|
-
v3 = v1 + v2 # Addition
|
|
309
|
-
v3 = v1 - v2 # Subtraction
|
|
310
|
-
v3 = v1 * scalar # Scalar multiplication
|
|
311
|
-
v3 = scalar * v1 # Reverse scalar multiplication
|
|
312
|
-
v3 = v1 / scalar # Scalar division
|
|
313
|
-
v3 = v1 * v2 # Component-wise multiplication
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
#### Vector Operations
|
|
317
|
-
|
|
318
|
-
```python
|
|
319
|
-
dot = v1.dot(v2) # Dot product (float)
|
|
320
|
-
cross = v1.cross(v2) # Cross product (vec3) - Left-hand rule
|
|
321
|
-
length = v.length() # Vector length
|
|
322
|
-
v.normalize() # Normalize in-place
|
|
323
|
-
normalized = v.normcopy() # Return normalized copy
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
#### Additional Methods
|
|
327
|
-
|
|
328
|
-
```python
|
|
329
|
-
v.lenxy() # Length in XY plane
|
|
330
|
-
v.sqrlen() # Squared length
|
|
331
|
-
v.abslen() # Sum of absolute components
|
|
332
|
-
v.isINF() # Check for infinity
|
|
333
|
-
v.flipX() # Flip X component
|
|
334
|
-
v.flipY() # Flip Y component
|
|
335
|
-
v.flipZ() # Flip Z component
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
#### Static Methods
|
|
339
|
-
|
|
340
|
-
```python
|
|
341
|
-
v = vec3.min3(a, b, c) # Component-wise minimum
|
|
342
|
-
v = vec3.max3(a, b, c) # Component-wise maximum
|
|
343
|
-
v = vec3.rnd() # Random vector
|
|
344
|
-
v = vec3.lerp(a, b, t) # Linear interpolation
|
|
345
|
-
angle = vec3.angle(a, b) # Angle between vectors
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
---
|
|
349
|
-
|
|
350
|
-
### quat - Quaternion
|
|
351
|
-
|
|
352
|
-
#### Constructors
|
|
353
|
-
|
|
354
|
-
```python
|
|
355
|
-
q = quat() # Identity quaternion
|
|
356
|
-
q = quat(w, x, y, z) # From components
|
|
357
|
-
q = quat(angle, axis) # From angle-axis
|
|
358
|
-
q = quat(v1, v2) # From two vectors
|
|
359
|
-
```
|
|
360
|
-
|
|
361
|
-
#### Properties
|
|
362
|
-
|
|
363
|
-
```python
|
|
364
|
-
q.w, q.x, q.y, q.z # Quaternion components
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
#### Operations
|
|
368
|
-
|
|
369
|
-
```python
|
|
370
|
-
q3 = q1 + q2 # Addition
|
|
371
|
-
q3 = q1 * q2 # Multiplication (composition)
|
|
372
|
-
v_rotated = q * v # Rotate vector
|
|
373
|
-
q3 = q1 / q2 # Division
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
#### Methods
|
|
377
|
-
|
|
378
|
-
```python
|
|
379
|
-
q.normalize() # Normalize in-place
|
|
380
|
-
normalized = q.normalized() # Return normalized copy
|
|
381
|
-
conj = q.conj() # Conjugate
|
|
382
|
-
length = q.length() # Length
|
|
383
|
-
dot = q1.dot(q2) # Dot product
|
|
384
|
-
angle = q1.angle_to(q2) # Angle to another quaternion
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
#### Conversion
|
|
388
|
-
|
|
389
|
-
```python
|
|
390
|
-
# From Euler angles
|
|
391
|
-
q.from_eulers(pitch, yaw, roll)
|
|
392
|
-
|
|
393
|
-
# From vectors
|
|
394
|
-
q.fromvectors(v1, v2)
|
|
395
|
-
|
|
396
|
-
# Advanced
|
|
397
|
-
q_exp = q.exp() # Exponential
|
|
398
|
-
q_log = q.log() # Logarithm
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
---
|
|
402
|
-
|
|
403
|
-
### coord3 - 3D Coordinate System
|
|
404
|
-
|
|
405
|
-
A `coord3` represents a complete 3D coordinate frame with:
|
|
406
|
-
- **Position** (o): Origin in 3D space
|
|
407
|
-
- **Rotation** (ux, uy, uz): Three orthonormal axes
|
|
408
|
-
- **Scale** (s): Scale factors for each axis
|
|
409
|
-
|
|
410
|
-
#### Constructors
|
|
411
|
-
|
|
412
|
-
```python
|
|
413
|
-
c = coord3() # Identity frame
|
|
414
|
-
c = coord3(x, y, z) # Position only
|
|
415
|
-
c = coord3(x, y, z, pitch, yaw, roll) # Position + rotation (Euler)
|
|
416
|
-
c = coord3(x, y, z, qw, qx, qy, qz) # Position + rotation (quaternion)
|
|
417
|
-
c = coord3(position) # From vec3
|
|
418
|
-
c = coord3(ux, uy, uz) # From three axes
|
|
419
|
-
c = coord3(angle, axis) # From angle-axis rotation
|
|
420
|
-
c = coord3(quaternion) # From quaternion
|
|
421
|
-
c = coord3(position, quaternion, scale) # Full specification
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
#### Properties
|
|
425
|
-
|
|
426
|
-
```python
|
|
427
|
-
c.o # Origin (vec3)
|
|
428
|
-
c.ux, c.uy, c.uz # Axis vectors (vec3)
|
|
429
|
-
c.s # Scale (vec3)
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
#### Static Factory Methods
|
|
433
|
-
|
|
434
|
-
```python
|
|
435
|
-
# Common constructors (NEW in v2.4.0)
|
|
436
|
-
c = coord3.identity() # Identity coordinate system at origin
|
|
437
|
-
c = coord3.zero() # Zero coordinate system (same as identity)
|
|
438
|
-
c = coord3.from_position(pos) # At position with identity rotation
|
|
439
|
-
c = coord3.from_rotation(quaternion) # At origin with rotation
|
|
440
|
-
|
|
441
|
-
# Advanced constructors
|
|
442
|
-
c = coord3.from_axes(ux, uy, uz) # From three axes
|
|
443
|
-
c = coord3.from_angle(angle, axis) # From angle-axis
|
|
444
|
-
c = coord3.look_at(eye, target, up) # Look-at transformation
|
|
445
|
-
c = coord3.from_forward(pos, forward, up) # From position and forward direction
|
|
446
|
-
c = coord3.from_eulers(pitch, yaw, roll) # From Euler angles
|
|
447
|
-
```
|
|
448
|
-
|
|
449
|
-
#### Transformations
|
|
450
|
-
|
|
451
|
-
```python
|
|
452
|
-
# Transform point from local to world
|
|
453
|
-
world_pos = local_pos * coord
|
|
454
|
-
|
|
455
|
-
# Transform point from world to local
|
|
456
|
-
local_pos = world_pos / coord
|
|
457
|
-
|
|
458
|
-
# Combine coordinate systems
|
|
459
|
-
c3 = c1 * c2
|
|
460
|
-
```
|
|
461
|
-
|
|
462
|
-
#### Operations
|
|
463
|
-
|
|
464
|
-
```python
|
|
465
|
-
c3 = c1 + c2 # Add (translate)
|
|
466
|
-
c3 = c1 - c2 # Subtract
|
|
467
|
-
c3 = c1 * c2 # Multiply (compose transformations)
|
|
468
|
-
c3 = c1 / c2 # Divide
|
|
469
|
-
equal = c1 == c2 # Equality check
|
|
470
|
-
```
|
|
471
|
-
|
|
472
|
-
#### Methods
|
|
473
|
-
|
|
474
|
-
```python
|
|
475
|
-
pos = c.pos() # Get position vector
|
|
476
|
-
vec = c.tovec() # Convert to vector
|
|
477
|
-
c.rot(angle, axis) # Rotate by angle-axis
|
|
478
|
-
c.rot(quaternion) # Rotate by quaternion
|
|
479
|
-
equal = c1.equal_dirs(c2) # Check if axes are equal
|
|
480
|
-
hash_val = c.hash() # Hash value
|
|
481
|
-
serial = c.serialise() # Serialize to string
|
|
482
|
-
c.dump() # Print debug info
|
|
483
|
-
```
|
|
484
|
-
|
|
485
|
-
---
|
|
486
|
-
|
|
487
|
-
## Usage Examples
|
|
488
|
-
|
|
489
|
-
### Vector Mathematics
|
|
490
|
-
|
|
491
|
-
```python
|
|
492
|
-
from coordinate_system import vec3
|
|
493
|
-
|
|
494
|
-
# Create vectors
|
|
495
|
-
v1 = vec3(1, 0, 0)
|
|
496
|
-
v2 = vec3(0, 1, 0)
|
|
497
|
-
|
|
498
|
-
# Basic operations
|
|
499
|
-
v3 = v1 + v2 # vec3(1, 1, 0)
|
|
500
|
-
v4 = v1 * 5 # vec3(5, 0, 0)
|
|
501
|
-
|
|
502
|
-
# Dot and cross products
|
|
503
|
-
dot = v1.dot(v2) # 0.0 (perpendicular)
|
|
504
|
-
cross = v1.cross(v2) # vec3(0, 0, -1) in left-handed system (X × Y = -Z)
|
|
505
|
-
|
|
506
|
-
# Length and normalization
|
|
507
|
-
length = v1.length() # 1.0
|
|
508
|
-
v_normalized = v1.normcopy() # Unit vector
|
|
509
|
-
|
|
510
|
-
# Linear interpolation
|
|
511
|
-
v_mid = vec3.lerp(v1, v2, 0.5) # vec3(0.5, 0.5, 0)
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
### Quaternion Rotations
|
|
515
|
-
|
|
516
|
-
```python
|
|
517
|
-
from coordinate_system import vec3, quat
|
|
518
|
-
|
|
519
|
-
# Create quaternion from angle-axis
|
|
520
|
-
import math
|
|
521
|
-
axis = vec3(0, 0, 1) # Z axis
|
|
522
|
-
angle = math.pi / 2 # 90 degrees
|
|
523
|
-
q = quat(angle, axis)
|
|
524
|
-
|
|
525
|
-
# Rotate vector
|
|
526
|
-
v = vec3(1, 0, 0)
|
|
527
|
-
rotated = q * v # Approximately vec3(0, 1, 0)
|
|
528
|
-
|
|
529
|
-
# Create quaternion from two vectors
|
|
530
|
-
v_from = vec3(1, 0, 0)
|
|
531
|
-
v_to = vec3(0, 1, 0)
|
|
532
|
-
q = quat(v_from, v_to)
|
|
533
|
-
|
|
534
|
-
# Quaternion composition
|
|
535
|
-
q1 = quat(math.pi/4, vec3(0, 0, 1)) # 45° around Z
|
|
536
|
-
q2 = quat(math.pi/4, vec3(0, 1, 0)) # 45° around Y
|
|
537
|
-
combined = q1 * q2 # Combined rotation
|
|
538
|
-
|
|
539
|
-
# Euler angles
|
|
540
|
-
q.from_eulers(pitch=0.1, yaw=0.2, roll=0.3)
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
### Coordinate System Transformations
|
|
544
|
-
|
|
545
|
-
```python
|
|
546
|
-
from coordinate_system import vec3, quat, coord3
|
|
547
|
-
import math
|
|
548
|
-
|
|
549
|
-
# Create a coordinate system at position (5, 10, 15)
|
|
550
|
-
frame = coord3(5, 10, 15)
|
|
551
|
-
|
|
552
|
-
# Create with rotation
|
|
553
|
-
q = quat(math.pi/4, vec3(0, 0, 1)) # 45° rotation
|
|
554
|
-
frame = coord3(vec3(5, 10, 15), q, vec3(1, 1, 1))
|
|
555
|
-
|
|
556
|
-
# Transform points between coordinate systems
|
|
557
|
-
world_point = vec3(10, 0, 0)
|
|
558
|
-
local_point = world_point / frame # World to local
|
|
559
|
-
back_to_world = local_point * frame # Local to world
|
|
560
|
-
|
|
561
|
-
# Hierarchical transformations
|
|
562
|
-
parent = coord3(0, 5, 0)
|
|
563
|
-
child = coord3(3, 0, 0)
|
|
564
|
-
child_in_world = child * parent
|
|
565
|
-
|
|
566
|
-
# Create look-at transformation (custom implementation needed)
|
|
567
|
-
def look_at(eye, target, up=vec3(0, 1, 0)):
|
|
568
|
-
forward = (target - eye).normcopy()
|
|
569
|
-
right = forward.cross(up).normcopy() # Left-hand cross product
|
|
570
|
-
up_corrected = right.cross(forward)
|
|
571
|
-
return coord3.from_axes(right, up_corrected, forward)
|
|
572
|
-
|
|
573
|
-
camera = look_at(vec3(10, 10, 10), vec3(0, 0, 0))
|
|
574
|
-
```
|
|
575
|
-
|
|
576
|
-
### Practical Applications
|
|
577
|
-
|
|
578
|
-
#### Camera System
|
|
579
|
-
|
|
580
|
-
```python
|
|
581
|
-
from coordinate_system import vec3, quat, coord3
|
|
582
|
-
import math
|
|
583
|
-
|
|
584
|
-
class Camera:
|
|
585
|
-
def __init__(self, position, target, up=vec3(0, 1, 0)):
|
|
586
|
-
self.frame = self.create_look_at(position, target, up)
|
|
587
|
-
|
|
588
|
-
def create_look_at(self, eye, target, up):
|
|
589
|
-
forward = (target - eye).normcopy()
|
|
590
|
-
right = forward.cross(up).normcopy() # Left-hand cross product
|
|
591
|
-
up_corrected = right.cross(forward)
|
|
592
|
-
|
|
593
|
-
c = coord3()
|
|
594
|
-
c.o = eye
|
|
595
|
-
c.ux = right
|
|
596
|
-
c.uy = up_corrected
|
|
597
|
-
c.uz = forward
|
|
598
|
-
return c
|
|
599
|
-
|
|
600
|
-
def move_forward(self, distance):
|
|
601
|
-
self.frame.o = self.frame.o + self.frame.uz * distance
|
|
602
|
-
|
|
603
|
-
def orbit(self, angle_h, angle_v):
|
|
604
|
-
q_h = quat(angle_h, vec3(0, 1, 0))
|
|
605
|
-
q_v = quat(angle_v, self.frame.ux)
|
|
606
|
-
self.frame.rot(q_h)
|
|
607
|
-
self.frame.rot(q_v)
|
|
608
|
-
|
|
609
|
-
# Usage
|
|
610
|
-
cam = Camera(vec3(0, 5, 10), vec3(0, 0, 0))
|
|
611
|
-
cam.orbit(0.1, 0) # Orbit horizontally
|
|
612
|
-
cam.move_forward(1.0) # Move forward
|
|
613
|
-
```
|
|
614
|
-
|
|
615
|
-
#### Physics Simulation
|
|
616
|
-
|
|
617
|
-
```python
|
|
618
|
-
from coordinate_system import vec3, quat, coord3
|
|
619
|
-
|
|
620
|
-
class RigidBody:
|
|
621
|
-
def __init__(self, position=vec3(0, 0, 0)):
|
|
622
|
-
self.frame = coord3(position)
|
|
623
|
-
self.velocity = vec3(0, 0, 0)
|
|
624
|
-
self.angular_velocity = vec3(0, 0, 0)
|
|
625
|
-
|
|
626
|
-
def apply_force(self, force, dt):
|
|
627
|
-
self.velocity = self.velocity + force * dt
|
|
628
|
-
|
|
629
|
-
def update(self, dt):
|
|
630
|
-
# Update position
|
|
631
|
-
self.frame.o = self.frame.o + self.velocity * dt
|
|
632
|
-
|
|
633
|
-
# Update rotation
|
|
634
|
-
if self.angular_velocity.length() > 0:
|
|
635
|
-
angle = self.angular_velocity.length() * dt
|
|
636
|
-
axis = self.angular_velocity.normcopy()
|
|
637
|
-
q = quat(angle, axis)
|
|
638
|
-
self.frame.rot(q)
|
|
639
|
-
|
|
640
|
-
# Usage
|
|
641
|
-
body = RigidBody(vec3(0, 10, 0))
|
|
642
|
-
gravity = vec3(0, -9.8, 0)
|
|
643
|
-
|
|
644
|
-
dt = 1.0 / 60.0 # 60 FPS
|
|
645
|
-
for _ in range(100):
|
|
646
|
-
body.apply_force(gravity, dt)
|
|
647
|
-
body.update(dt)
|
|
648
|
-
```
|
|
649
|
-
|
|
650
|
-
---
|
|
651
|
-
|
|
652
|
-
## Advanced Features
|
|
653
|
-
|
|
654
|
-
### Interpolation
|
|
655
|
-
|
|
656
|
-
The package provides helper functions for interpolation:
|
|
657
|
-
|
|
658
|
-
```python
|
|
659
|
-
from coordinate_system import lerp
|
|
660
|
-
|
|
661
|
-
# Linear interpolation
|
|
662
|
-
v1 = vec3(0, 0, 0)
|
|
663
|
-
v2 = vec3(10, 10, 10)
|
|
664
|
-
v_mid = lerp(v1, v2, 0.5) # vec3(5, 5, 5)
|
|
665
|
-
```
|
|
666
|
-
|
|
667
|
-
For spherical linear interpolation (slerp), use quaternions:
|
|
668
|
-
|
|
669
|
-
```python
|
|
670
|
-
q1 = quat() # Identity
|
|
671
|
-
q2 = quat(1.57, vec3(0, 0, 1)) # 90° rotation
|
|
672
|
-
|
|
673
|
-
# Manual slerp implementation or use quaternion methods
|
|
674
|
-
# (depends on availability in your binding)
|
|
675
|
-
```
|
|
676
|
-
|
|
677
|
-
### Constants
|
|
678
|
-
|
|
679
|
-
```python
|
|
680
|
-
from coordinate_system import ZERO3, UNITX, UNITY, UNITZ, ONE3, ONE4, ONEC
|
|
681
|
-
|
|
682
|
-
ZERO3 # Zero vector vec3(0, 0, 0)
|
|
683
|
-
UNITX # Unit X vector vec3(1, 0, 0)
|
|
684
|
-
UNITY # Unit Y vector vec3(0, 1, 0)
|
|
685
|
-
UNITZ # Unit Z vector vec3(0, 0, 1)
|
|
686
|
-
ONE3 # Unit scale vec3(1, 1, 1)
|
|
687
|
-
ONE4 # Identity quaternion quat(1, 0, 0, 0)
|
|
688
|
-
ONEC # World coordinate system coord3()
|
|
689
|
-
```
|
|
690
|
-
|
|
691
|
-
---
|
|
692
|
-
|
|
693
|
-
## Building from Source
|
|
694
|
-
|
|
695
|
-
### Prerequisites
|
|
696
|
-
|
|
697
|
-
- C++17 compatible compiler
|
|
698
|
-
- Python 3.7+
|
|
699
|
-
- pybind11
|
|
700
|
-
|
|
701
|
-
### Windows
|
|
702
|
-
|
|
703
|
-
```bash
|
|
704
|
-
# Install Visual Studio 2019+ with C++ tools
|
|
705
|
-
pip install pybind11 wheel
|
|
706
|
-
python setup.py build
|
|
707
|
-
python setup.py bdist_wheel
|
|
708
|
-
```
|
|
709
|
-
|
|
710
|
-
### Linux
|
|
711
|
-
|
|
712
|
-
```bash
|
|
713
|
-
sudo apt install build-essential python3-dev
|
|
714
|
-
pip3 install pybind11 wheel
|
|
715
|
-
python3 setup.py build
|
|
716
|
-
python3 setup.py bdist_wheel
|
|
717
|
-
```
|
|
718
|
-
|
|
719
|
-
### macOS
|
|
720
|
-
|
|
721
|
-
```bash
|
|
722
|
-
xcode-select --install
|
|
723
|
-
pip3 install pybind11 wheel
|
|
724
|
-
python3 setup.py build
|
|
725
|
-
python3 setup.py bdist_wheel
|
|
726
|
-
```
|
|
727
|
-
|
|
728
|
-
---
|
|
729
|
-
|
|
730
|
-
## Performance
|
|
731
|
-
|
|
732
|
-
Benchmark on Intel i7-10700K @ 3.8GHz:
|
|
733
|
-
|
|
734
|
-
| Operation | Ops/second |
|
|
735
|
-
|-----------|-----------|
|
|
736
|
-
| Vector addition | 5,200,000 |
|
|
737
|
-
| Dot product | 4,800,000 |
|
|
738
|
-
| Cross product | 3,500,000 |
|
|
739
|
-
| Normalize | 2,100,000 |
|
|
740
|
-
| Quaternion rotation | 1,800,000 |
|
|
741
|
-
|
|
742
|
-
---
|
|
743
|
-
|
|
744
|
-
## Contributing
|
|
745
|
-
|
|
746
|
-
Contributions are welcome! Please:
|
|
747
|
-
|
|
748
|
-
1. Fork the repository
|
|
749
|
-
2. Create a feature branch
|
|
750
|
-
3. Make your changes
|
|
751
|
-
4. Add tests
|
|
752
|
-
5. Submit a pull request
|
|
753
|
-
|
|
754
|
-
---
|
|
755
|
-
|
|
756
|
-
## License
|
|
757
|
-
|
|
758
|
-
MIT License - see [LICENSE](LICENSE) file for details
|
|
759
|
-
|
|
760
|
-
Copyright (c) 2024-2025 PanGuoJun
|
|
761
|
-
|
|
762
|
-
---
|
|
763
|
-
|
|
764
|
-
## Author
|
|
765
|
-
|
|
766
|
-
**PanGuoJun** (romeosoft)
|
|
767
|
-
|
|
768
|
-
- Email: 18858146@qq.com
|
|
769
|
-
- GitHub: [panguojun/Coordinate-System](https://github.com/panguojun/Coordinate-System)
|
|
770
|
-
|
|
771
|
-
---
|
|
772
|
-
|
|
773
|
-
## Links
|
|
774
|
-
|
|
775
|
-
- **PyPI**: https://pypi.org/project/coordinate-system/
|
|
776
|
-
- **GitHub**: https://github.com/panguojun/Coordinate-System
|
|
777
|
-
- **Mathematical Foundation**: [MATHEMATICAL_FOUNDATION.md](https://github.com/panguojun/Coordinate-System/blob/main/MATHEMATICAL_FOUNDATION.md)
|
|
778
|
-
- **Issues**: https://github.com/panguojun/Coordinate-System/issues
|
|
779
|
-
|
|
780
|
-
---
|
|
781
|
-
|
|
782
|
-
## Changelog
|
|
783
|
-
|
|
784
|
-
### Version 1.2.0 (2025-10-22)
|
|
785
|
-
- ✅ Cross-platform support (Windows, Linux, macOS)
|
|
786
|
-
- ✅ Updated documentation
|
|
787
|
-
- ✅ Improved API consistency
|
|
788
|
-
- ✅ Added more usage examples
|
|
789
|
-
- ✅ Performance optimizations
|
|
790
|
-
|
|
791
|
-
### Version 1.1.0 (2024-09-08)
|
|
792
|
-
- Initial PyPI release
|
|
793
|
-
- Windows support
|
|
794
|
-
- Core vec3, quat, coord3 classes
|
|
795
|
-
|
|
796
|
-
---
|
|
797
|
-
|
|
798
|
-
## Acknowledgments
|
|
799
|
-
|
|
800
|
-
Built with ❤️ using:
|
|
801
|
-
- C++17
|
|
802
|
-
- pybind11
|
|
803
|
-
- Python
|
|
804
|
-
|
|
805
|
-
---
|
|
806
|
-
|
|
807
|
-
**Note**: For the latest updates and documentation, visit the [GitHub repository](https://github.com/panguojun/Coordinate-System).
|