pygf 0.1.0__tar.gz

pygf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 王炳辉
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygf-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: pygf
+Version: 0.1.0
+Summary: Graphics math types for Python: vectors, matrices and quaternions on ctypes
+Author-email: 王炳辉 <binghui.wang@foxmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Time-Coder/pygf
+Project-URL: Source, https://github.com/Time-Coder/pygf
+Keywords: graphics,math,linear-algebra,vector,matrix,quaternion,ctypes,gltf,usd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+Dynamic: license-file
+
+# pygf
+
+Graphics math types for Python: vectors, matrices and quaternions, built on
+`ctypes` with no compiled extension. A shared foundation for scene-description,
+shading-language and rendering projects that all need the same numeric types and
+none of them should have to depend on each other for them.
+
+```python
+from pygf import double3, matrix4d, quatd, funcs
+
+v = double3(1.0, 0.0, 0.0)
+
+m = matrix4d() * 2.0                    # element-wise, `*` not matrix multiply
+m = matrix4d() * matrix4d()             # matrix multiply
+n = funcs.normalize(double3(3.0, 4.0, 0.0))
+w = funcs.dot(v, n)
+
+r = quatd(0.0, 1.0, 0.0, 0.0) * v       # rotate by a half turn about X
+```
+
+Note that `*` is matrix multiply for `matrix * matrix`, matching what this layer
+has always done, and that there is no `@` operator.
+
+## What is here
+
+| Group | Types |
+|---|---|
+| Vectors | `float2/3/4`, `double2/3/4`, `int2/3/4`, `uint2/3/4`, `half2/3/4`, `bool2/3/4` |
+| Matrices | `matrix2/3/4` in `f`, `d`, `b` |
+| Quaternions | `quatf`, `quatd`, `quath`, `quatb` |
+| USD aliases | `point3f`, `normal3f`, `vector3f`, `color3f`, `texCoord2f`, `frame4d`, ... |
+| Functions | the GLSL-shaped set: `abs`, `mix`, `clamp`, `cross`, `dot`, `normalize`, `determinant`, `inverse`, ... |
+
+## Design notes
+
+**Element types, not operators.** A `genVec` counts its slots with `_slot_count`,
+which is `rows` for a matrix and the element count for a vector or quaternion.
+`len()` is ctypes' *flat* element count on a matrix -- 16 for a 4x4 -- while
+`m[i]` yields the i-th row, so driving the element-wise loops with `len()`
+overruns. The element-wise helpers in `funcs.py` also *recurse*, because a matrix
+slot is a row and handing that row to `builtins.abs` still fails once the count is
+right.
+
+**Matrices are square only.** `genMat.mat_type` refuses a non-square shape rather
+than silently truncating it to `shape[0] x shape[0]`.
+
+**`half` is a real IEEE-754 binary16.** Stored as `c_uint16` bit patterns in
+private fields, converted on access through `struct`'s native `e` format. The
+component names are properties, so `ctypes.Structure.__setattr__` still reaches
+them. Overflow saturates to infinity rather than raising, which is what a GPU
+buffer would hold.
+
+**Swizzles are runtime-dynamic.** `genVec.__getattr__` builds every combination
+of `xyzw` / `rgba` / `stpq` on demand, so the class carries no swizzle
+declarations at runtime. A generated `if TYPE_CHECKING:` block declares all of
+them for type checkers and IDEs; see `tools/sync_swizzle_blocks.py`.
+
+**numpy interop.** Importing `pygf` replaces `numpy.array` so that it reads a
+container as its components: `np.array(matrix3d())` gives a `(3, 3)` array
+rather than ctypes' flat storage. Arguments it does not recognise are passed
+straight through.
+
+## Layout
+
+```
+pygf/          the package
+tests/         test_pygf.py -- stdlib plus pygf, nothing else
+tools/         sync_swizzle_blocks.py -- the only writer of the swizzle blocks
+static_check.py
+publish.py
+```
+
+## Development
+
+```
+python -m pip install -e ".[dev]"
+python static_check.py
+python tests/test_pygf.py
+```
+
+`static_check.py` runs `compileall`, `ruff check --fix`, and `ty check`. Every
+check in the test file corresponds to a defect that type checking or review
+surfaced; the module docstring in the test lists them.
+
+After changing `genVec`'s swizzle generation, regenerate the declaration blocks:
+
+```
+python tools/sync_swizzle_blocks.py
+```
+
+It is idempotent, and it is the only thing that writes those blocks.
+
+## Publishing
+
+```
+python -m pip install -e ".[publish]"
+python publish.py build
+python publish.py
+```
+
+## License
+
+MIT

pygf-0.1.0/README.md

@@ -0,0 +1,103 @@
+# pygf
+
+Graphics math types for Python: vectors, matrices and quaternions, built on
+`ctypes` with no compiled extension. A shared foundation for scene-description,
+shading-language and rendering projects that all need the same numeric types and
+none of them should have to depend on each other for them.
+
+```python
+from pygf import double3, matrix4d, quatd, funcs
+
+v = double3(1.0, 0.0, 0.0)
+
+m = matrix4d() * 2.0                    # element-wise, `*` not matrix multiply
+m = matrix4d() * matrix4d()             # matrix multiply
+n = funcs.normalize(double3(3.0, 4.0, 0.0))
+w = funcs.dot(v, n)
+
+r = quatd(0.0, 1.0, 0.0, 0.0) * v       # rotate by a half turn about X
+```
+
+Note that `*` is matrix multiply for `matrix * matrix`, matching what this layer
+has always done, and that there is no `@` operator.
+
+## What is here
+
+| Group | Types |
+|---|---|
+| Vectors | `float2/3/4`, `double2/3/4`, `int2/3/4`, `uint2/3/4`, `half2/3/4`, `bool2/3/4` |
+| Matrices | `matrix2/3/4` in `f`, `d`, `b` |
+| Quaternions | `quatf`, `quatd`, `quath`, `quatb` |
+| USD aliases | `point3f`, `normal3f`, `vector3f`, `color3f`, `texCoord2f`, `frame4d`, ... |
+| Functions | the GLSL-shaped set: `abs`, `mix`, `clamp`, `cross`, `dot`, `normalize`, `determinant`, `inverse`, ... |
+
+## Design notes
+
+**Element types, not operators.** A `genVec` counts its slots with `_slot_count`,
+which is `rows` for a matrix and the element count for a vector or quaternion.
+`len()` is ctypes' *flat* element count on a matrix -- 16 for a 4x4 -- while
+`m[i]` yields the i-th row, so driving the element-wise loops with `len()`
+overruns. The element-wise helpers in `funcs.py` also *recurse*, because a matrix
+slot is a row and handing that row to `builtins.abs` still fails once the count is
+right.
+
+**Matrices are square only.** `genMat.mat_type` refuses a non-square shape rather
+than silently truncating it to `shape[0] x shape[0]`.
+
+**`half` is a real IEEE-754 binary16.** Stored as `c_uint16` bit patterns in
+private fields, converted on access through `struct`'s native `e` format. The
+component names are properties, so `ctypes.Structure.__setattr__` still reaches
+them. Overflow saturates to infinity rather than raising, which is what a GPU
+buffer would hold.
+
+**Swizzles are runtime-dynamic.** `genVec.__getattr__` builds every combination
+of `xyzw` / `rgba` / `stpq` on demand, so the class carries no swizzle
+declarations at runtime. A generated `if TYPE_CHECKING:` block declares all of
+them for type checkers and IDEs; see `tools/sync_swizzle_blocks.py`.
+
+**numpy interop.** Importing `pygf` replaces `numpy.array` so that it reads a
+container as its components: `np.array(matrix3d())` gives a `(3, 3)` array
+rather than ctypes' flat storage. Arguments it does not recognise are passed
+straight through.
+
+## Layout
+
+```
+pygf/          the package
+tests/         test_pygf.py -- stdlib plus pygf, nothing else
+tools/         sync_swizzle_blocks.py -- the only writer of the swizzle blocks
+static_check.py
+publish.py
+```
+
+## Development
+
+```
+python -m pip install -e ".[dev]"
+python static_check.py
+python tests/test_pygf.py
+```
+
+`static_check.py` runs `compileall`, `ruff check --fix`, and `ty check`. Every
+check in the test file corresponds to a defect that type checking or review
+surfaced; the module docstring in the test lists them.
+
+After changing `genVec`'s swizzle generation, regenerate the declaration blocks:
+
+```
+python tools/sync_swizzle_blocks.py
+```
+
+It is idempotent, and it is the only thing that writes those blocks.
+
+## Publishing
+
+```
+python -m pip install -e ".[publish]"
+python publish.py build
+python publish.py
+```
+
+## License
+
+MIT

pygf-0.1.0/pygf/__init__.py

@@ -0,0 +1,173 @@
+from .alias import (
+    color3d,
+    color3f,
+    color3h,
+    color4d,
+    color4f,
+    color4h,
+    frame4d,
+    normal3d,
+    normal3f,
+    normal3h,
+    point3d,
+    point3f,
+    point3h,
+    texCoord2d,
+    texCoord2f,
+    texCoord2h,
+    texCoord3d,
+    texCoord3f,
+    texCoord3h,
+    vector3d,
+    vector3f,
+    vector3h,
+)
+from .bool2 import bool2
+from .bool3 import bool3
+from .bool4 import bool4
+from .double2 import double2
+from .double3 import double3
+from .double4 import double4
+from .float2 import float2
+from .float3 import float3
+from .float4 import float4
+from .funcs import (
+    abs,
+    acos,
+    acosh,
+    all,
+    any,
+    asin,
+    asinh,
+    atan,
+    atanh,
+    ceil,
+    clamp,
+    conjugate,
+    cos,
+    cosh,
+    cross,
+    determinant,
+    distance,
+    dot,
+    equal,
+    exp,
+    exp2,
+    exp10,
+    faceforward,
+    floor,
+    fract,
+    greaterThan,
+    greaterThanEqual,
+    inverse,
+    inversesqrt,
+    length,
+    lessThan,
+    lessThanEqual,
+    log,
+    log2,
+    log10,
+    matrixCompMult,
+    max,
+    min,
+    mix,
+    mod,
+    normalize,
+    not_,
+    notEqual,
+    outerProduct,
+    pow,
+    reflect,
+    refract,
+    round,
+    roundEven,
+    sign,
+    sin,
+    sinh,
+    sizeof,
+    smoothstep,
+    sqrt,
+    step,
+    tan,
+    tanh,
+    trace,
+    transpose,
+    trunc,
+)
+from .genMat import MatType, genMat
+from .genMat2 import Mat2Type, genMat2
+from .genMat3 import Mat3Type, genMat3
+from .genMat4 import Mat4Type, genMat4
+from .genQuat import QuatType, genQuat
+from .genType import MathForm, genType
+from .genVec import VecType, genVec
+from .genVec2 import Vec2Type, genVec2
+from .genVec3 import Vec3Type, genVec3
+from .genVec4 import Vec4Type, genVec4
+from .half2 import half2
+from .half3 import half3
+from .half4 import half4
+from .helper import Number, patch_nparray
+from .int2 import int2
+from .int3 import int3
+from .int4 import int4
+from .matrix2b import matrix2b
+from .matrix2d import matrix2d
+from .matrix2f import matrix2f
+from .matrix3b import matrix3b
+from .matrix3d import matrix3d
+from .matrix3f import matrix3f
+from .matrix4b import matrix4b
+from .matrix4d import matrix4d
+from .matrix4f import matrix4f
+from .quatb import quatb
+from .quatd import quatd
+from .quatf import quatf
+from .quath import quath
+from .uint2 import uint2
+from .uint3 import uint3
+from .uint4 import uint4
+
+__all__ = [
+    "MathForm",
+    "genType", "Number",
+    "genVec", "VecType",
+    "genVec2", "Vec2Type",
+    "genVec3", "Vec3Type",
+    "genVec4", "Vec4Type",
+    "genMat", "MatType",
+    "genMat2", "Mat2Type",
+    "genMat3", "Mat3Type",
+    "genMat4", "Mat4Type",
+    "genQuat", "QuatType",
+    "bool2", "bool3", "bool4",
+    "int2", "int3", "int4",
+    "uint2", "uint3", "uint4",
+    "half2", "half3", "half4",
+    "float2", "float3", "float4",
+    "double2", "double3", "double4",
+    "matrix2b", "matrix3b", "matrix4b",
+    "matrix2f", "matrix3f", "matrix4f",
+    "matrix2d", "matrix3d", "matrix4d",
+    "quatb", "quatf", "quatd", "quath",
+    "color3h", "color3f", "color3d",
+    "color4h", "color4f", "color4d",
+    "texCoord2h", "texCoord2f", "texCoord2d",
+    "texCoord3h", "texCoord3f", "texCoord3d",
+    "normal3h", "normal3f", "normal3d",
+    "point3h", "point3f", "point3d",
+    "vector3h", "vector3f", "vector3d",
+    "frame4d",
+
+    "abs", "sign", "floor", "ceil", "trunc", "round", "roundEven", "fract", "mod",
+    "min", "max", "clamp", "mix", "step", "smoothstep", "sqrt", "inversesqrt",
+    "pow", "exp", "exp2", "exp10", "log", "log2", "log10",
+    "sin", "cos", "tan", "asin", "acos", "atan",
+    "sinh", "cosh", "tanh", "asinh", "acosh", "atanh",
+    "length", "normalize", "distance", "dot", "cross", "faceforward", "reflect", "refract",
+    "transpose", "determinant", "inverse", "trace", "conjugate",
+    "matrixCompMult", "outerProduct", "lessThan", "lessThanEqual",
+    "greaterThan", "greaterThanEqual", "equal", "notEqual", "any", "all", "not_", "sizeof"
+]
+
+patch_nparray()

pygf-0.1.0/pygf/alias.py

@@ -0,0 +1,84 @@
+from .double2 import double2
+from .double3 import double3
+from .double4 import double4
+from .float2 import float2
+from .float3 import float3
+from .float4 import float4
+from .half2 import half2
+from .half3 import half3
+from .half4 import half4
+from .matrix4d import matrix4d
+
+
+class color3d(double3):
+    pass
+
+class color3f(float3):
+    pass
+
+class color3h(half3):
+    pass
+
+
+class color4d(double4):
+    pass
+
+class color4f(float4):
+    pass
+
+class color4h(half4):
+    pass
+
+
+class normal3d(double3):
+    pass
+
+class normal3f(float3):
+    pass
+
+class normal3h(half3):
+    pass
+
+
+class point3d(double3):
+    pass
+
+class point3f(float3):
+    pass
+
+class point3h(half3):
+    pass
+
+
+class vector3d(double3):
+    pass
+
+class vector3f(float3):
+    pass
+
+class vector3h(half3):
+    pass
+
+
+class frame4d(matrix4d):
+    pass
+
+
+class texCoord2d(double2):
+    pass
+
+class texCoord2f(float2):
+    pass
+
+class texCoord2h(half2):
+    pass
+
+
+class texCoord3d(double3):
+    pass
+
+class texCoord3f(float3):
+    pass
+
+class texCoord3h(half3):
+    pass