inklet 2.5.0__tar.gz

inklet-2.5.0/.gitattributes

@@ -0,0 +1,2 @@
+# PDB records use fixed-width, space-padded columns.
+*.pdb whitespace=-blank-at-eol

inklet-2.5.0/.github/workflows/checks.yml

@@ -0,0 +1,77 @@
+name: Release checks
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  figures:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.12'
+      - name: Install fonts and independent PDF renderer
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y fonts-dejavu-core fonts-dejavu-extra fonts-noto-core fonts-liberation fonts-urw-base35 poppler-utils
+          google-chrome --version
+          pdftoppm -v
+      - name: Install locked test dependencies
+        run: |
+          uv venv
+          uv pip install -r requirements-ci.txt -e .
+          .venv/bin/inklet doctor
+      - name: Unit and integration tests
+        run: .venv/bin/python -m pytest -q --junitxml=out/tests.xml
+      - name: Generated API documentation
+        run: .venv/bin/python tools/gen_api.py --check
+      - name: Build documentation with strict link validation
+        run: |
+          uv pip install -r requirements-docs.txt
+          .venv/bin/python -m mkdocs build --strict
+          .venv/bin/python -m pytest -q tests/test_docs_site.py
+      - name: Build the v2.5 publication review
+        run: .venv/bin/inklet build examples/v25_document.py --output out/v25 --name document
+      - name: Complete figure visual regressions
+        run: .venv/bin/python tools/visual_check.py --output out/visual
+      - name: Complete figure performance checks
+        run: .venv/bin/python tools/benchmark_v2.py --output out/benchmarks
+      - name: Twenty-panel mixed-media stress test
+        run: .venv/bin/python tools/stress20.py --output out/stress20
+      - name: Preserve review artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: figure-checks
+          path: out/
+          retention-days: 7
+          if-no-files-found: ignore
+
+  wheel:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Build and install with core dependencies only
+        run: |
+          uv build --wheel --out-dir out/dist
+          uv run --no-project python tools/check_wheel.py out/dist/inklet-*.whl

inklet-2.5.0/.gitignore

@@ -0,0 +1,35 @@
+# Environments and local configuration
+.venv/
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.remember/
+
+# Builds, exports and development experiments
+/out/
+/tmp/
+/dist/
+/build/
+/site/
+*.egg-info/
+/figures/out/
+/examples/*.svg
+/examples/*.png
+/examples/*.pdf
+/stress/*.svg
+/stress/*.png
+/stress/*.pdf
+/stress/panels/*.svg
+/stress/panels/*.png
+/stress/panels/*.pdf
+/stress/electro/*.svg
+/stress/electro/*.png
+/stress/electro/*.pdf
+
+# Editor / OS files
+.DS_Store
+.idea/
+.vscode/

inklet-2.5.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 2.5.0
+
+- Prepare the standalone release tree with an MIT license, third-party notices,
+  maintained examples, and explicit source-distribution contents.
+- Refresh Blender's evaluated scene after baking Line Art so SVG exports retain
+  every baked stroke. Invalidate earlier bake caches and verify fresh exports.
+- Rework the README around installation, a runnable first figure and supported
+  workflows. Add task-based guides, command-line and troubleshooting references,
+  a searchable local documentation site and contributor instructions.
+- Execute introductory documentation examples and validate links and site
+  navigation in CI. Preserve the generated API reference and existing recipes.
+
+- Add nested subfigures that share measurement caches and inherit page themes.
+- Add measured compositions with named children, algebraic size/anchor references,
+  cycle detection, branch and return routing, and editable architecture modules.
+- Reserve panel-letter space during layout. Resolve deferred callouts after
+  insets and brackets, considering measured marks and existing furniture.
+- Add general publication presets for physical widths, typography, stroke sizes,
+  export defaults and print-size diagnostics; record profiles in manifests.
+- Add component/severity filters and search to review pages, plus saved-revision
+  overlays and pixel differences. Handle size/DPI changes without invalid scores.
+  Watch mode compares successive successful builds and preserves failed-build output.
+- Rebuild the AlphaFold architecture and full proteome layout with public
+  composition APIs, removing their custom renderer classes. Preserve the reviewed
+  PDF appearance and existing SVG tolerance.
+- Add a complete v2.5 example, regression coverage and installed-wheel checks.
+
+
+- Migrate AlphaFold Figure 1e to measured module components and named ports;
+  migrate the complete proteome figure to live plots, data and category filters.
+- Add `derive()` for explicit transformations of live data dependencies.
+- Consolidate thin-stroke warnings within named, intentionally touching artwork
+  while retaining all targets; show component paths in HTML and JSON findings.
+- Check unit tests, complete SVG/PDF figures, performance budgets and isolated
+  wheel installations in GitHub Actions. Lock the scientific test dependencies.
+- Preserve the native mesh when optional trimesh repair dependencies are absent.
+- Avoid global theme changes when importing the Nature examples, and keep the
+  generated API reference consistent across Python versions.
+- Check repeated drawing identities with a set, avoiding quadratic placement
+  work for dense scatter layers.
+
+## 2.0.0
+
+- Add live documents with versioned plot and component definitions, compiled
+  snapshots, bounded geometry caches and deterministic drawing identities.
+- Fit plots to physical pages with weighted tracks, spanning cells, shared
+  furniture margins and explicit errors for unsatisfiable constraints.
+- Add datasets, shared numeric scales, series with uncertainty, live category
+  selections, units, data sources and file dependencies.
+- Resolve inherited paint once for SVG and PDF while preserving clipping,
+  transformations and group compositing.
+- Add `inklet build`, `watch` and `doctor`, clickable SVG diagnostics, JSON
+  findings, and export manifests with data, font and asset provenance.
+- Add six complete v2 visual fixtures, performance budgets and compatibility
+  comparisons for all four Nature Figure 1 reconstructions.
+- Avoid repeated child-index construction in crowding diagnostics for large
+  drawings, and isolate document themes throughout text and shape creation.
+
+Existing Diagram, Panel and Figure APIs remain available. See
+[the migration guide](docs/migration.md) and [v2 guide](docs/v2.md).

inklet-2.5.0/CONTRACT.md

@@ -0,0 +1,76 @@
+# Inklet module contract
+
+The core represents geometry, styles, primitives and immutable diagram trees.
+Typesetting measures text; layout places nodes; routing connects them;
+diagnostics inspect the resolved figure; rendering exports it.
+
+Core changes affect every layer. Preserve the invariants below and add focused
+regression coverage for changes to measurement, placement or traversal.
+
+## Non-negotiables
+
+- **Millimetres everywhere.** `core.units.mm("89mm") -> 89.0`, `pt(7) -> 2.47`.
+  Bare numbers are already mm. Pixels exist only inside a raster backend.
+- **y grows downward** (SVG convention). North is `-y`.
+- **Primitives are centred on their local origin.**
+- **Deterministic output.** No `uuid4`, no dict-order dependence, no
+  `time`/`random`. The same script must emit byte-identical SVG twice.
+- **Core never measures text.** `TextPrim` arrives pre-shaped.
+- Python 3.11 or later, `from __future__ import annotations`, dataclasses, type hints.
+  Stdlib + the deps already in `pyproject.toml` only.
+
+## Core API you build against
+
+```python
+Vec2(x, y)                  # + - * dot cross length normalized perp angle
+Affine(a,b,c,d,e,f)         # .translation .rotation .scaling  A @ B = B then A
+                            # .apply(pt) .apply_vector(v) .inverse() .is_identity
+Rect(x0,y0,x1,y1)           # .width .height .center .corners .union .pad .overlap
+Envelope                    # .extent(unit_dir) -> float|None   support function
+                            # .union .transform .pad .bbox()
+Trace                       # .exit(origin, dir) .boundary_point(origin, dir)
+Style(...)                  # all fields Optional, None = inherit; .over(base) .with_()
+Prim: RectPrim(w,h,radius) EllipsePrim(rx,ry)
+      PathPrim(subpaths,filled,fill_rule)   # fill_rule: nonzero | evenodd
+      TextPrim(lines,font_family,font_size,ascent,descent,align,font_path,
+               ...,features)   # features = sorted (tag, value) pairs it was
+                               # shaped with; core.text_features() canonicalises
+      ImagePrim(source,width,height,pixel_size,outline,data,smooth)
+                         # data = encoded PNG/JPEG bytes; then source is a label
+                         # smooth: None = backend's call, False = nearest-neighbour
+      PhantomPrim(box)   # occupies space, draws nothing, empty trace
+Envelope.expand(t,r,b,l)   # padding: a disc sweep when uniform, box sum when not
+Diagram(envelope_override=...)  # claim space the contents do not; trace untouched
+Diagram(prim=, children=(), transform=, style=, kind=, name=, notes={})
+  .local_envelope .envelope   # local = before self.transform; plain = after
+  .local_trace .trace .bbox .local_bbox .width .height .extent(dir)
+  .anchor(name, (u,v)|Vec2)   # (u,v) are fractions of local bbox, (0,0)=top-left
+  .anchor_point(name)         # compass: n s e w ne nw se sw center. LOCAL:
+                              # pre-transform. Placement.point re-reads the
+                              # compass off the placed box (M10)
+  .registered_point(name)     # a registered anchor, looking through the
+                              # wrappers translated/rotated/scaled leave
+                              # behind, or None (M16)
+  .note(key, value) -> self   # per-node annotation core does not read;
+  .notes                      # survives replace/apply_theme/build (M17)
+  .carry_notes(source)        # inherit a single child's notes, moved into
+                              # this node's frame (M19)
+note_through(affine, value)   # how one note value moves: a Rect is re-cornered,
+                              # everything else is carried verbatim (M19)
+  .at(name) -> AnchorRef
+  .placed(affine) .translated .rotated .scaled .centered .styled .named .copy
+  .walk() .find(name)
+resolve(root) -> {id: Placement}   # Placement: .world .style .envelope .trace
+                                   #            .bbox .point(anchor) .depth
+flatten(root) -> [RenderItem]      # RenderItem: .prim .world .style .id .name
+world_point(ref_or_diagram, placements) -> Vec2
+```
+
+Combinators **wrap, never rewrite**: `d.translated(3)` returns a new parent
+whose child is the very same `d` object, so a caller's handle stays valid after
+being stacked. Never place one Diagram object twice — `resolve()` raises.
+
+## Testing
+
+`.venv/bin/python -m pytest tests/ -q`. Place regression tests alongside the relevant feature tests. Test behaviour
+and numerical results.

inklet-2.5.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to Inklet
+
+Use a focused change with a runnable example or minimal reproducer. Describe
+the resulting behavior and how it was checked. Keep numerical inputs and
+expected results explicit; use simulated data when source data cannot be shared.
+
+## Development environment
+
+From a checkout with Python 3.12 and `uv` installed:
+
+```sh
+uv venv --python 3.12
+uv pip install -r requirements-ci.txt -e .
+.venv/bin/python -m inklet doctor
+```
+
+The lock file is the tested scientific environment. Vector-only development
+needs fewer packages, but the full suite also exercises optional image and 3D
+features. CI installs fonts, Chrome and Poppler as described in
+[release checks](docs/release-checks.md).
+
+## Test a change
+
+Run the tests relevant to the modified behavior first:
+
+```sh
+.venv/bin/python -m pytest -q tests/test_document.py tests/test_document_v25.py
+```
+
+For a release or a broad rendering change:
+
+```sh
+.venv/bin/python -m pytest -q
+.venv/bin/python tools/gen_api.py --check
+.venv/bin/python tools/visual_check.py --output out/visual
+.venv/bin/python tools/benchmark_v2.py --output out/benchmarks
+.venv/bin/python tools/stress20.py --output out/stress20
+```
+
+Visual checks need the preview tools. Inspect differences before changing a
+baseline; see [visual test instructions](tests/visual/README.md). Performance
+results are machine-dependent, so include workload and environment details.
+
+## Documentation
+
+User guides live in `docs/`, with navigation in `mkdocs.yml`. Markdown should
+remain readable in both GitHub and the local site. Link to repository files
+relatively; the site hook includes gallery images and converts other
+out-of-docs links to repository URLs. This avoids duplicate copies of examples
+and preview assets.
+
+```sh
+uv pip install -r requirements-docs.txt
+.venv/bin/python -m pytest -q tests/test_docs.py tests/test_cookbook.py tests/test_guides.py tests/test_docs_site.py
+.venv/bin/python tools/gen_api.py --check
+.venv/bin/python -m mkdocs build --strict
+.venv/bin/python -m mkdocs serve
+```
+
+The static site is written to `out/docs-site/`; local serving uses port 8000.
+The [MkDocs configuration reference](https://www.mkdocs.org/user-guide/configuration/)
+describes navigation and strict validation. CI builds the site and uploads it
+as an artifact. There is no automatic public deployment.
+
+New introductory guides should use complete Python examples or clearly state
+what preceding blocks they depend on. `tests/test_guides.py` executes registered
+pages in a temporary directory, sharing a namespace only within each page.
+Prefix a Python fence with `<!-- Requires preview renderers. -->` followed by
+a blank line for examples needing preview tools; those examples are exercised
+when the tools are available. File-dependent fragments
+should state which user files are needed.
+
+`docs/api.md` is generated from public signatures and docstrings. Change the
+source docstrings or `tools/gen_api.py`, then regenerate it; do not edit the
+generated file by hand. Keep instructions literal and document limitations
+alongside the corresponding feature.
+
+## Repository structure
+
+| Path | Purpose |
+|---|---|
+| `src/inklet/document/` | Live definitions, data, measurement and compilation |
+| `src/inklet/plot/`, `draw/`, `layout/`, `links/` | Charts, geometry composition and routing |
+| `src/inklet/three/`, `assets/` | Meshes, vector 3D and image processing |
+| `src/inklet/typeset/`, `themes/` | Shaped text and physical styling |
+| `src/inklet/render/`, `diagnostics/` | Export backends, review and drawing checks |
+| `tests/` | Unit, integration and visual regression checks |
+| `examples/`, `figures/`, `stress/` | Runnable figures and larger workloads |
+| `tools/` | Documentation generation, wheel checks and benchmarks |
+
+Read [the core contract](CONTRACT.md) before changing fundamental geometry,
+and [the compilation contract](docs/design/v2.md) before changing dependency,
+measurement or caching semantics. Update [the changelog](CHANGELOG.md) for
+user-visible changes.

inklet-2.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapika and Inklet contributors
+
+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.

inklet-2.5.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: inklet
+Version: 2.5.0
+Summary: Scientific figures with live data, measured layout, and consistent vector exports.
+Project-URL: Repository, https://github.com/Mapika/inklet
+Project-URL: Documentation, https://github.com/Mapika/inklet/blob/master/docs/index.md
+Project-URL: Issues, https://github.com/Mapika/inklet/issues
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Python: >=3.11
+Requires-Dist: fonttools>=4.53
+Requires-Dist: uharfbuzz>=0.39
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: pygments<3,>=2.18; extra == 'docs'
+Provides-Extra: images
+Requires-Dist: numpy>=1.24; extra == 'images'
+Requires-Dist: pillow>=10.0; extra == 'images'
+Provides-Extra: three
+Requires-Dist: numpy>=1.24; extra == 'three'
+Requires-Dist: trimesh>=4.0; extra == 'three'
+Description-Content-Type: text/markdown
+
+# Inklet
+
+**Scientific figures from Python, with measured layout and editable SVG/PDF output.**
+
+Combine plots, diagrams, images and native 3D artwork on a page sized in
+millimetres. Keep data and labels live, compile the figure, and inspect its
+layout and print diagnostics before exporting.
+
+[Get started](docs/quickstart.md) · [Documentation](docs/index.md) ·
+[Examples](docs/examples.md) · [API reference](docs/api.md)
+
+![Twenty-panel Inklet figure with 3D surfaces, architecture diagrams, dense scatter, statistical charts, polar plots and Sankey flows](gallery/stress20.png)
+
+This [twenty-panel stress test](docs/stress20.md) includes 30,000 scatter points,
+5,580 mesh triangles and 7,200 vector events. Its data are simulated. Only the
+dense scatter and scalar field are rasterized; the other artwork remains vector.
+
+## Install
+
+Python **3.11 or later** is required. Install from this repository using an
+account with access to `Mapika/inklet`:
+
+```sh
+git clone https://github.com/Mapika/inklet.git
+cd inklet
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+SVG/PDF output and the built-in 3D renderer need no browser or external rendering
+engine. Text needs an installed font. For PNG layers and visual review, install
+`python -m pip install -e '.[images]'` plus Chrome/Chromium and Poppler.
+See [installation](docs/installation.md) for system packages, Windows activation,
+optional dependencies and environment checks.
+
+## Your first figure
+
+Save this as `first_figure.py` and run `python first_figure.py`:
+
+```python
+import inklet as i
+
+
+def make_document():
+    data = i.dataset(
+        {'time': [0, 1, 2, 3], 'signal': [1, 3, 2, 4]},
+        name='response',
+        source=i.Source('Quickstart demonstration', method='simulated'),
+    )
+    plot = i.plot_spec(x=(0, 3), y=(0, 5))
+    plot.line(data.points('time', 'signal'), name='Signal', stroke='#176b9b')
+    plot.axes(x='Time / s', y='Signal / mV').legend(side='bottom')
+
+    doc = i.publication('single-column').document()
+    doc.add('response', plot, min_height=55)
+    return doc
+
+
+if __name__ == '__main__':
+    figure = make_document().compile()
+    figure.save('response.svg', 'response.pdf')
+    print(figure.report())
+```
+
+The document measures axis labels and the legend, fits the plot to an 89 mm
+page, and saves SVG and PDF with embedded text. It does not shrink the font to
+make the plot fit. The [quickstart](docs/quickstart.md) continues with live data
+edits, multiple panels and review exports.
+
+## Build, inspect, revise
+
+With the [preview dependencies](docs/installation.md#visual-review) installed:
+
+```sh
+inklet doctor
+inklet build first_figure.py --output out/review
+inklet watch first_figure.py --output out/review
+```
+
+`build` writes the vector files, PNG previews, diagnostics, a provenance manifest
+and a local HTML review page. `watch` serves a preview at
+`http://127.0.0.1:8765/` and rebuilds when the authoring code changes. Review pages
+support diagnostic filters, SVG highlights and comparisons with a saved revision.
+
+For an environment without preview tools, use
+`inklet build first_figure.py --output out/review --vectors-only`.
+
+## What you can build
+
+| Task | Main tools | Guide |
+|---|---|---|
+| Multi-panel figures | `document`, `subfigure`, weighted columns, spans, panel letters | [Layout](docs/layout.md) |
+| Scientific plots | `plot_spec`, axes, bands, distributions, heatmaps, insets, polar plots | [Plotting](docs/plotting.md) |
+| Data-driven revisions | `Dataset`, `Series`, shared scales, categories, `derive`, source records | [Live data](docs/data.md) |
+| Architecture and flow diagrams | `composition`, `module`, named ports, measured connections, `graph` | [Diagrams](docs/diagrams.md) |
+| 3D and image panels | `solid`, `model`, `scene`, `asset`, explicit file dependencies | [3D and images](docs/three-images.md) |
+| Publication exports | Physical presets, embedded or outlined text, SVG/PDF, review bundles | [Export and review](docs/export-review.md) |
+
+## How Inklet works
+
+A `Document` holds live definitions. `compile()` measures their contents, places
+them, routes connections and produces a snapshot used by both export backends.
+Updating a dataset or named instruction invalidates dependent components;
+unchanged definitions can reuse their cached geometry. Earlier snapshots remain
+unchanged.
+
+Numeric lengths, including low-level text sizes, are **millimetres**. Use
+`i.pt(8)` for an 8-point text size; publication profile options such as
+`font_pt=8` take points explicitly. Plot coordinates follow their data scales.
+
+The direct `Figure`, `Panel` and `Diagram` APIs remain supported for fixed
+drawings. See [the authoring model](docs/concepts.md) for when to use each layer.
+
+## Scope and limits
+
+- Layout respects physical constraints. Impossible fits raise `LayoutError`;
+  changing page width does not automatically rearrange the number of columns.
+- Diagnostics help find collisions, small type and other print issues. Review
+  the rendered figure as well; a clean report does not establish scientific accuracy.
+- Rasterization keeps dense exports compact, but dense-scatter rebuilds can
+  still be expensive. The [stress report](docs/stress20.md) records the workload,
+  timings and remaining limitations.
+- Reproducible appearance requires consistent inputs, fonts and dependencies.
+  The export manifest records dataset and font hashes for comparison.
+
+## Documentation and development
+
+Start at the [documentation index](docs/index.md). The source Markdown is readable
+on GitHub; a searchable site can also be served locally:
+
+```sh
+python -m pip install -e '.[docs]'
+python -m mkdocs serve
+```
+
+See [contributing](CONTRIBUTING.md) for tests, documentation checks and visual
+regressions. Existing users can consult [migration](docs/migration.md),
+[the v2.5 changes](docs/v2.5.md) and [the changelog](CHANGELOG.md).
+
+## License
+
+Inklet code is available under the [MIT license](LICENSE). Included third-party
+meshes and structural data retain their own terms; see
+[third-party notices](THIRD_PARTY_NOTICES.md).