ngk 0.0.1__tar.gz

ngk-0.0.1/.cargo/config.toml

@@ -0,0 +1,2 @@
+[env]
+PYO3_NO_PYTHON = "1"

ngk-0.0.1/.cursor/rules/map_book_instructions.mdc

@@ -0,0 +1,24 @@
+---
+description: Canonical combinatorial / generalized map (gmap) theory lives in private_doc book; consult it in chunks, not whole-file reads
+alwaysApply: true
+---
+
+# Combinatorial maps & GMap — reference source
+
+**Authoritative domain knowledge** for combinatorial maps, generalized maps (GMap / gmap), darts, involutions, and related constructions in this codebase is written in the **combinatorial maps book** stored under the project’s private documentation:
+
+- **Location:** `private_doc/Combinatorial_Maps_Book/Combinatorial_Maps_Book.md`
+
+Treat that material as the **source of truth** when reasoning about theory, definitions, or algorithms for maps and gmaps in this repo.
+
+## How to use the book (LLM context limits)
+
+The book is **too large to load entirely** into a single context window. **Do not** read or paste the full file in one shot.
+
+Instead:
+
+1. **Search and slice:** Use workspace search, grep, or partial reads (`read_file` with `offset` / `limit`) to open **only the sections** relevant to the current question (chapter headings, keywords: e.g. “generalized map”, “involution”, “sew”, “alpha”, “dimension”).
+2. **Iterate:** If the first excerpt is insufficient, refine keywords or read the **next adjacent chunk** — still in small portions.
+3. **Prefer targeted questions:** Formulate what definition or construction you need, then locate that passage rather than skimming from the start.
+
+This keeps answers aligned with the book while staying within practical context size.

ngk-0.0.1/.github/workflows/deploy-pages.yml

@@ -0,0 +1,70 @@
+name: Deploy visualization to GitHub Pages
+
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Setup wasm-pack
+        uses: jetli/wasm-pack-action@v0.4.0
+        with:
+          version: latest
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: visualization/package-lock.json
+
+      - name: Install dependencies
+        working-directory: visualization
+        run: npm ci
+
+      - name: Build visualization
+        working-directory: visualization
+        env:
+          VITE_BASE_PATH: /ngk/
+        run: npm run build
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: visualization/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

ngk-0.0.1/.gitignore

@@ -0,0 +1,45 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# Generated by cargo mutants
+# Contains mutation testing data
+**/mutants.out*/
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Added by cargo
+
+/target
+
+# Private documentation (not tracked)
+private_doc/
+
+# Local junction onto skills/ — recreate per machine, see AGENTS.md
+.claude/skills
+
+# Visualization frontend
+visualization/node_modules/
+visualization/dist/
+visualization/src/wasm/
+
+# Python local builds
+.venv/
+.uv-cache/
+.uv-python/
+__pycache__/
+**/__pycache__/
+*.pyd
+

ngk-0.0.1/.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

ngk-0.0.1/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "rust-analyzer.debug.engine": "vadimcn.vscode-lldb",
+    "rust-analyzer.runnables.extraEnv": {
+        "RUSTUP_TOOLCHAIN": "stable-x86_64-pc-windows-gnu",
+        "Path": "C:\\msys64\\ucrt64\\bin;C:\\Users\\romai\\.cargo\\bin;C:\\Windows\\System32;C:\\Windows"
+    },
+    "rust-analyzer.debug.engineSettings": {
+        "vadimcn.vscode-lldb": {
+            "expressions": "simple",
+            "sourceLanguages": ["rust"]
+        }
+    },
+    "lldb.script.lang.rust.toolchain": "stable-x86_64-pc-windows-gnu"
+}

ngk-0.0.1/AGENTS.md

@@ -0,0 +1,177 @@
+# AGENTS.md — NGK (Nales Geometry Kernel)
+
+Working memory for agents (Claude Code, Codex, and others) in `D:\Projets\ngk`.
+Read this first, then the pointed-to docs.
+
+Shared skills live in `skills/` at the repo root — `.claude/skills` is a local
+directory junction onto it, so skill content is edited in one place only.
+The junction is machine-local (not tracked in git); recreate it after a fresh
+clone with:
+
+```powershell
+New-Item -ItemType Junction -Path ".claude\skills" -Target "skills"
+```
+
+## What this project is
+
+NGK is an experimental **CAD geometric kernel written in Rust**, built around
+**generalized maps (3-GMaps)** instead of a classical winged-edge / OCCT-style B-Rep.
+
+The core bet: represent topology combinatorially first (darts + α involutions),
+and attach geometry (points, curves, surfaces) as *payload attributes* on cells.
+Sewing, unsewing, extrusion, splitting and cell traversal then become explicit,
+provable operations on the map rather than ad-hoc record surgery.
+
+Goal is a **robust, state-of-the-art kernel for CAD** — not a history-based
+parametric modeler. Operations mutate one map and return explicit handles.
+
+- Crate: `ngk`, edition 2024, MIT. `cdylib` + `rlib`, plus an `ngk` binary.
+- Deps: `nalgebra`, `slotmap`, `serde`, `thiserror`, `radians`.
+- Features: `python` (pyo3/maturin), `wasm` (wasm-bindgen).
+- Author: Jojain (romain.ferru@gmail.com). Pages demo: https://jojain.github.io/ngk/
+
+## Layering (bottom → top)
+
+| Layer | Path | Role |
+|---|---|---|
+| `topology` | `src/topology/` | The GMap: darts, α0..α3, cells, keys, attributes, transactional editing |
+| `geometry` | `src/geometry/` | Pure math: points, curves, surfaces, NURBS, intersections, bbox, tolerance |
+| `builders` | `src/builders/` | Low-level topology construction (`&mut GMap`), one transaction each |
+| `modeling` | `src/modeling/` | Thin user-facing standalone shape builders (`block`, `revolve`, …) |
+| `healing` | `src/healing/` | Removes topology that carries no shape (`i`-removal passes over `builders::removal`) |
+| `tessellate` | `src/tessellate/` | Geometry/BRep → polylines + indexed meshes |
+| `viz` | `src/viz/` | `VizScene` assembly, dart/α overlays, debug viewer, ocp_vscode bridge |
+| `scripts` | `src/scripts/` | Named exploration scenes, registered in `SCRIPTS` |
+| `bindings` | `bindings/{common,python,wasm}` | pyo3 + wasm-bindgen surfaces |
+| `visualization/` | React + R3F + Vite | Playground consuming the wasm build |
+
+`src/model.rs` holds an embryonic `Model<P>` (owns one persistent `GMap`) —
+the target design lives in `docs/model_api.md` and is **not implemented yet**.
+
+## Topology core — key concepts
+
+- **`Dart`** — oriented traversal locator. Short-lived; may be destroyed by any edit.
+- **`Dim::{Zero,One,Two,Three}`** ↔ α0..α3 ↔ vertex/edge/face/(sheet|solid).
+  `GMAP_INVOLUTION_COUNT = 4`.
+- **Keys are the durable identity**: `VertexKey, EdgeKey, ProfileKey, FaceKey,
+  SheetKey, SolidKey` (slotmap `new_key_type!`). Public APIs select cells by key,
+  never by dart.
+- **Attributes** (`topology/attributes.rs`) store geometry + user payload per cell:
+  `VertexAttr{dart, point, data}`, `EdgeAttr{dart, curve, data}`, `FaceAttr`
+  (surface + pcurve loops), `ProfileAttr`, `SheetAttr`, `SolidAttr`.
+- **Orientation triple** (`docs/topology_orientation_refactor.md`):
+  `identity = XKey` · `default orientation = reference dart in XAttr` ·
+  `contextual orientation = dart carried by the view`.
+  `Orientation::{Same,Reversed}` composes and applies to vectors/scalars.
+- **Typed views** — `Vertex`, `Edge`, `Face`, `Profile`, `Sheet`, `Solid`, plus
+  `Shape<K, P>` (owned map + primary handle). *Traverse with these, not raw darts.*
+- **`Payload` trait** — type-level bundle of user data per dimension;
+  `StandardPayload` = `()` everywhere. Most types are generic over `P: Payload`.
+- **Profiles = face boundary loops; Sheets = solid shells.** They must be
+  **registered explicitly** (`add_profile` / `add_sheet`); commit rejects faces
+  or solids referencing unregistered components.
+
+### Transactions (read `src/topology/edit.md` — short and essential)
+
+`GMap::transaction` / `transaction_with_policy` is the atomic boundary for a
+modeling operation. The closure receives a **`TopologyEdit`** — the only public
+mutation capability (`add_dart`, `remove_dart`, `link`, `unlink`, `sew`, plus
+attribute create/remove/split/merge declarations).
+
+- One public builder = one transaction; composite builders pass the same
+  `&mut TopologyEdit` down to private `*_staged` helpers.
+- Any error, validation failure, identity-reconciliation failure or payload
+  policy failure restores the full transaction-start snapshot. Panics are **not** caught.
+- **Lineage**: `add_*` (fresh) / `add_*_split_from` (derived) / `merge_*_into`
+  (explicit survivor). At commit, merge chains resolve and `EditPolicy`
+  (e.g. `PreservePayload`) runs only on net externally-visible changes.
+- **Identity reconciliation** picks one surviving key per final cell;
+  transaction-start keys beat transaction-local ones. Local keys may vanish at commit.
+- Derived dart→key maps are one lazy `DerivedCellIndexes` cache, invalidated on mutation.
+
+## Geometry
+
+- 2D: `Curve2` (`Line2`, `Circle2`, `Ellipse2`, `NurbsCurve2`), `TrimmedCurve2`,
+  2D intersections (used for pcurves/imprints).
+- 3D: `Curve` (`Line`, `Circle`, NURBS), `Surface` (`Plane`, `Cylinder`,
+  `RuledSurface`, `SurfaceOfRevolution`, `NurbsSurface`), `BBox`, `Frame`, `Interval`.
+- Intersections: curve/curve, curve/surface, surface/surface with `IntersectionOptions`.
+- Tolerances: `LINEAR_TOLERANCE`, `ANGULAR_TOLERANCE`; point equality via
+  `PointCoincidence::coincides`.
+- **Analytic-first dispatch, certified NURBS fallback** (`intersections/analytic/`):
+  a recognized pair is answered in closed form *before* anything is converted or
+  decomposed; everything else takes the NURBS solver, which is also the
+  differential-test oracle. `intersect_analytic_*` return `Option<Result<..>>`:
+  `None` declines the pair (fall back), `Ok(..Empty)` certifies disjointness.
+  A pair in the table that reaches a case the `Curve` types cannot carry also
+  declines. Covered today: surface/surface plane×{plane,sphere,cylinder} and
+  sphere×sphere; curve/surface line×{plane,sphere,cylinder,cone} and
+  circle×{plane,sphere}; curve/curve line×line, line×circle, circle×circle.
+  Not covered: anything involving a cone surface pair, cylinder×cylinder,
+  circle×{cylinder,cone}.
+- **A `Curve` is an unbounded support, never trimmed to the cell carrying it.**
+  There is no `Curve::Bounded` variant: a line runs to infinity, a circle closes.
+  Which part is meant is said by **`TrimmedCurve`** (`geometry/dim3/trimmed.rs`)
+  — support + an `Interval` of its *native* parameters, kept as one value so the
+  halves cannot drift apart. It normalizes traversal (fraction 0 → 1 over the
+  span), unwraps periodic branches, and answers `contains` / `length` / `sub` /
+  `reversed`. `to_curve()` is the cut-down copy: exact, but NURBS, so reach for
+  it only when a curve that *is* the section is required (fitting a pcurve).
+- **2D mirrors 3D exactly.** A `Curve2` is an unbounded support in a surface's
+  parameter space — `Line2` extrapolates, `Circle2` and `Ellipse2` close — with
+  *native* parameters (a line's affine, a conic's angle in radians, a NURBS
+  curve's own knot domain); nothing is renormalized to `[0, 1]`.
+  **`TrimmedCurve2`** (`geometry/dim2/trimmed.rs`) is support + `Interval`, with
+  the same API as `TrimmedCurve`. Both carry the same shorthand constructors —
+  `segment`, `arc`, `ellipse_arc` (each anchoring the support so the span is
+  just the sweep) and `whole` (a support that already *is* the section, such as
+  an interpolated NURBS) — so a common span is never spelled out as a support
+  and an interval side by side. **Every pcurve is a `TrimmedCurve2`**: unlike an edge, it has
+  no bounding vertices to derive a span from, since a face stores no 2D vertex
+  positions. 2D intersection takes two spans, not two supports — the
+  subdivision search needs control polygons, which an infinite support has none
+  of — and returns fractions of each span.
+- **The span is derived only on an edge.** `EdgeAttr` stores no interval;
+  `Edge::trimmed_curve()` derives it from the bounding vertices plus the view's
+  orientation. Everything without vertices — `AnalyticSection`,
+  `SurfaceIntersectionBranch`, `FaceImprint`, `IntersectionSpan` — must carry
+  it: the minor and major arc between two points share both endpoints, so
+  endpoints alone name neither, and direction is load-bearing besides.
+- **A solver answers for the support.** Clip its result to the cells' own spans
+  (`TrimmedCurve::contains`) before treating it as a contact, or an edge picks up
+  hits from the part of its line no edge occupies.
+- `FaceImprint`'s two halves are **synchronized** — same fraction, same point —
+  which constrains the support: a `Circle` spans its arc in angle, the rational
+  quadratic its pcurve is fitted from does not, so an imprinted arc carries NURBS.
+- A section's 3D curve is exact; its **pcurve is exact only where a closed form
+
+## Working rules
+
+- **Deleting behaviour means deleting or adapting its tests.** A change is not
+  finished while a test still asserts, names, or explains the thing that was
+  removed. Grep for the concept by name, not just for compile errors: a test that
+  still passes can be testing nothing, and one whose name or comment describes the
+  old design is worse than no test, because it teaches the next reader something
+  false. Three outcomes, in order of preference — the test states a property that
+  survives, so keep it and fix the wording; the property moved to another shape,
+  so retarget it there; the property is genuinely gone, so delete the test. Never
+  leave the fourth. The same goes for doc comments, error-variant docs, `#[ignore]`
+  reasons, and plan files: an `#[ignore]` whose stated reason no longer applies
+  must be re-checked, since the test may now pass or fail for a new reason.
+- **Never `git checkout`, `git restore`, or `git stash` a file to undo your own
+  edit.** The working tree holds uncommitted work that is not recoverable. Undo
+  by making the inverse edit, and use a marker comment you can grep for when
+  adding temporary instrumentation.
+- **A comment describes the code as it is, never a plan for it.** Doc comments
+  and inline comments state what the thing does, why it is shaped that way, and
+  what it refuses — all in the present tense, all checkable against the code
+  next to them. They must not reference a plan document, a milestone, a stage
+  number, or a decision id (`plan/foo.md`, "stage 4", "D7", "arrives later",
+  "not implemented yet"), and must not describe behaviour that does not exist
+  yet. Keep the *reason* and drop the schedule: "a cylinder wall closes on
+  itself, which STEP cannot spell without a synthesized seam" is factual and
+  stays true; "…which needs seam synthesis (stage 4)" is a promise that rots the
+  moment the plan moves, and the reader cannot tell from the code whether it
+  still holds. Plans belong in `plan/`, which is where they can be revised in
+  one place. This applies to module docs, error-variant docs, test comments and
+  commit-adjacent prose alike.

ngk-0.0.1/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md — NGK
+
+Full project instructions for all agents live in [AGENTS.md](AGENTS.md) — read
+it first. This file exists only so Claude Code's own auto-load picks it up.