Develop

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  check:
+    name: Black and pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Sync
+        run: uv sync --locked --group dev
+      - name: Black
+        run: uv run black --check .
+      - name: Tests
+        run: uv run pytest

.github/workflows/publish.yml

@@ -2,23 +2,26 @@ name: Publish CwMath Package
 
 on:
   push:
-    branches:
-      - 'main'
+    tags:
+      - "v*"
 
 jobs:
   build-and-publish:
     name: Build and Publish
-    runs-on: 'ubuntu-latest'
+    runs-on: ubuntu-latest
     environment:
-          name: pypi
-          url: https://pypi.org/p/cwmath
+      name: pypi
+      url: https://pypi.org/p/cwmath
     permissions:
       id-token: write
+      contents: read
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-      - run: pip install build
-      - run: python -m build
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Install Python
+        run: uv python install 3.14
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

.gitignore

@@ -102,3 +102,5 @@ cython_debug/
 
 .idea/
 .vscode/
+
+.lp-scratch/

.readthedocs.yaml

@@ -3,11 +3,14 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    python: "3.12"
+    python: "3.14"
 
 mkdocs:
   configuration: mkdocs.yml
 
 python:
-   install:
-   - requirements: requirements.txt
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - dev

README.md

@@ -9,104 +9,64 @@
 [![Pulls](https://img.shields.io/github/issues-pr/cwapi3d/cwmath)](https://github.com/cwapi3d/cwmath/pulls)
 [![GitHub](https://img.shields.io/github/license/cwapi3d/cwmath)](https://choosealicense.com/licenses/mit/)
 
-This is the Cadwork Math Utilities library in Python.
+Dependency-free geometry types for cadwork plugin authors. Frozen `Point` / `Vec`
+pairs in 2D and 3D, a right-handed `Frame3`, `Plane3`, `Line3`, and projections.
+Python 3.14, managed with UV. Millimetres are the implicit length unit.
 
 ## Installation
 
-Install with pip:
-
 ```bash
-  pip install cwmath
+uv add cwmath
 ```
-
-## Contributing
 
-Contributions are always welcome!
-Before contributing, please check our [contributing agreement](CONTRIBUTING.md).
-
-## Roadmap
+From a checkout:
 
-- Guides
-- Examples
-- API Documentation
-
-## Authors
-
-- [@jspaquet](https://github.com/jspaquet)
-- [@Brunner246](https://github.com/Brunner246)
-
-## License
-
-[MIT](https://choosealicense.com/licenses/mit/)
+```bash
+uv sync --group dev
+```
 
-# Style Guide
+## Example
 
-Please follow the style guide below when adding functions.
-[Guidelines](GUIDELINES.md)
+Copy this into a cadwork plugin (or cadwork IDLE). It converts a host
+`point_3d`, builds a frame, drops a local point onto the XY plane, and
+converts the foot back for `cwapi3d`.
 
 ```python
-
-# imports:
-import math
-import sys
-from myclass import MyClass
-
-
-# example function
-def add_one(number: int) -> int:
-    """Increase number by one.
-
-    Function written by John Doe.
-
-    Args:
-        number: a number
-
-    Returns:
-        number increased by one
-    """
-    return number + 1
-
-
-# Aligned with opening delimiter.
-foo = long_function_name(var_one, var_two,
-                         var_three, var_four)
-
-if foo == 'blah':
-    do_blah_thing()
-do_one()
-do_two()
-do_three()
-
+import cadwork
+from cwmath import (
+    Frame3,
+    Plane3,
+    Point3,
+    Vec3,
+    project_point_on_plane,
+    to_point_3d,
+)
+
+origin = Point3.from_xyz(cadwork.point_3d(1000.0, 2000.0, 0.0))
+x_dir = Vec3.from_xyz(cadwork.point_3d(1.0, 0.0, 0.0))
+y_dir = Vec3.from_xyz(cadwork.point_3d(0.0, 1.0, 0.0))
+frame = Frame3.from_origin_xy(origin, x_dir, y_dir)
+
+local = Point3(50.0, 25.0, 10.0)
+world = frame.to_world(local)
+plane = Plane3.from_point_normal(origin, frame.z_axis)
+foot = project_point_on_plane(world, plane)
+result = to_point_3d(foot)
 ```
 
-# Examples
-```python
-import cadwork
-import element_controller as ec
-import geometry_controller as gc
+`to_point_3d` imports `cadwork` only at the call site. Unit tests inject a
+duck-typed factory instead of the host.
 
-import sys
+## Contributing
 
-sys.path.append("...\\...\cwmath\\src")
+Contributions are always welcome!
+Before contributing, please check our [contributing agreement](CONTRIBUTING.md).
 
-from cwmath import cwplane3d
-from cwmath import cwvector3d
+## Authors
 
-element_ids = ec.get_active_identifiable_element_ids()
-if len(element_ids) > 0:
-    point1 = gc.get_p1(*element_ids)
-    point2 = gc.get_p2(*element_ids)
-    yl = gc.get_yl(*element_ids)
-    plane = cwplane3d.CwPlane3d(point1,yl)
-    print(point1)
-    print(yl)
-    print(plane)
+- [@jspaquet](https://github.com/jspaquet)
+- [@Brunner246](https://github.com/Brunner246)
 
-    distance = plane.distance_to_point(cadwork.point_3d(0.,0.,0.))
-    print(distance)
+## License
 
-    vector1 = cwvector3d.CwVector3d.from_point_3d(point1)
-    vector2 = cwvector3d.CwVector3d.from_point_3d(point2)
-    norm =(vector2 - vector1).normalize()
-    print(norm)
-```
+[MIT](https://choosealicense.com/licenses/mit/)

docs/frame3.md

@@ -0,0 +1,13 @@
+# Frame3
+
+A frozen origin plus a right-handed orthonormal basis. Use
+`from_origin_and_axes` when the axes are already unit and orthogonal, or
+`from_origin_xy` to build `z = x × y` and orthonormalize.
+
+`to_world` / `to_local` map `Point3` with translation and `Vec3` by rotation
+only.
+
+::: cwmath.frame3.Frame3
+    options:
+        show_root_heading: true
+        show_source: true

docs/functions.md

@@ -1,5 +1,32 @@
-# CwMath
+# Functions
 
-::: src.cwmath.cwexamples
+Package-level helpers re-exported from `cwmath`.
+
+## Conversion
+
+::: cwmath.cadwork.to_point_3d
+    options:
+        show_root_heading: true
+        show_source: true
+
+## Projections
+
+::: cwmath.line3.project_point_on_line
+    options:
+        show_root_heading: true
+        show_source: true
+
+::: cwmath.plane3.project_point_on_plane
+    options:
+        show_root_heading: true
+        show_source: true
+
+## Tolerance
+
+`ABS_TOL = 1e-6`, `REL_TOL = 1e-9`. `==` on the types is exact; callers opt
+into closeness.
+
+::: cwmath.tolerance.is_close
     options:
-      show_source: true
+        show_root_heading: true
+        show_source: true

docs/index.md

@@ -1,9 +1,41 @@
 # Cadwork Math Utilities
 
-CwMath is an open source project in which Python functions are developed and made available by the community, for the community. CwMath is a subproject of the API of cadwork.
+`cwmath` is a small, dependency-free geometry library for cadwork 3d plugin
+authors. Frozen `Point` / `Vec` types in 2D and 3D, a right-handed `Frame3`,
+`Plane3`, `Line3`, and projections of a point onto a line or a plane.
+
+Import the public types from the package root:
+
+```python
+from cwmath import Point3, Vec3, Frame3, Plane3, Line3, to_point_3d
+```
 
 [Cadwork Python Documentation](https://docs.cadwork.com/projects/cwapi3dpython/en/latest/){.button-63}
 
+## Types
+
+- [Point3](point3.md) / [Vec3](vec3.md) — 3D affine pair, convertible to `cadwork.point_3d`
+- [Point2](point2.md) / [Vec2](vec2.md) — 2D affine pair
+- [Frame3](frame3.md) — local ↔ world for points and vectors
+- [Plane3](plane3.md) / [Line3](line3.md) — reference plane and infinite line
+- [Functions](functions.md) — `to_point_3d`, projections, `is_close`
+
+Cadwork millimetres are the implicit length unit. `==` is exact IEEE equality;
+use `is_close` when you want a tolerance.
+
+## Host conversion
+
+`Point3.from_xyz` / `Vec3.from_xyz` accept anything with `.x`, `.y`, `.z`
+(including `cadwork.point_3d`). `to_point_3d` imports `cadwork` only at the
+call site so CI can run without the host. Smoke-test the real adapter once in
+cadwork IDLE:
+
+```python
+from cwmath import Point3, to_point_3d
+
+to_point_3d(Point3(1, 2, 3))  # a real cadwork.point_3d
+```
+
 ![Backup Text](img/math.jpeg "https://elink.io/p/all-about-paula-incorvati-99ec81e")
 
 ## Agreement

docs/line3.md

@@ -0,0 +1,10 @@
+# Line3
+
+A frozen infinite line: origin plus a unit direction. Build with
+`from_origin_direction` or `from_points`. `project` is the closest point;
+`parameter` is the corresponding `t`.
+
+::: cwmath.line3.Line3
+    options:
+        show_root_heading: true
+        show_source: true