patchcraft 0.5.5__tar.gz → 0.5.7__tar.gz

{patchcraft-0.5.5 → patchcraft-0.5.7}/.pre-commit-config.yaml

@@ -1,8 +1,8 @@
 # Runs the gates CI runs, before the commit rather than after it.
 #
 # Deliberately absent: `ruff-format`. This project has never used it and
-# adopting it here would reformat 36 of 65 files in a commit that changed no
-# behaviour. `ruff check` is the gate; formatting is not.
+# adopting it here would reformat about half the tree (CONTRIBUTING.md has the
+# count) in a commit that changed no behaviour. `ruff check` is the gate; formatting is not.
 #
 # `mypy` runs through the project environment rather than through a pre-commit
 # virtualenv, because it needs torch to resolve any annotation in `src/` and

{patchcraft-0.5.5 → patchcraft-0.5.7}/AGENTS.md

@@ -128,9 +128,11 @@ connectives; one idea per paragraph. `README.md` is a call page, not a manual:
 the manual is [`docs/GUIDE.md`](docs/GUIDE.md), and complex examples belong
 there.
 
-Documents that state a version go stale. There is exactly one version string
-left in the documentation, the BibTeX entry in GUIDE section 9, plus
-[`CITATION.cff`](CITATION.cff). Do not add a third.
+Documents that state a version go stale. A release bumps three: the BibTeX
+entry in GUIDE section 9, [`CITATION.cff`](CITATION.cff), and the release
+named at the top of [`STATUS.md`](STATUS.md). [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md)
+names the version it measured, and changes only when it is re-measured. Do
+not add another.
 
 ## 2. Before you touch anything
 

{patchcraft-0.5.5 → patchcraft-0.5.7}/CHANGELOG.md

@@ -6,6 +6,197 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.7] - 2026-10-10
+
+Integer images, end to end. `extract` takes every dtype at every dilation,
+and `reconstruct` takes the five integer dtypes and returns them exactly in
+every legal geometry, since integer sums do not round. Every float result is
+unchanged: `extract`'s new single path is bit-identical to the one it
+replaces. The full suite passes on both code paths at the declared floor and
+at the newest releases, and the 126,736-geometry sweep, now with an integer
+round trip, passes on both paths.
+
+### Added
+
+- **Integer images through `extract` and `reconstruct`, exact in every legal
+  geometry.** These are steps 1 and 2 of ADR 0004, shipped together as the ADR
+  requires. `extract` takes every dtype at every dilation, because it is now
+  one strided window view and one copy for all of them: bit-identical to the
+  `F.unfold` path it replaced for floats, and 3.9 times faster at dilation 2
+  on 3x1024x1024. `reconstruct` takes `uint8`, `int8`, `int16`, `int32` and
+  `int64` and returns each pixel's exact mean rounded half to even, the
+  rounding `resize` already applies to integers. For patches from `extract`
+  that mean is the pixel itself in every legal geometry, with no count-map
+  rule, since integer sums do not round. Nothing overflows: up to `int32` the
+  sum is taken in `int64`, and `int64` values are split by their pixel's count
+  into a quotient and a remainder before they are added. `bool` and complex
+  patches are refused with a `ValueError`, `stitch` stays float-only, and the
+  accelerator leaves integers to torch. `tests/test_integer.py` checks the
+  round trip over the sampled geometry space, all 126,736 geometries under
+  `PATCHCRAFT_SWEEP_FULL=1`, for `uint8` and `int64`, and the mean of
+  disagreeing patches against Python integers in every dtype; deliberately
+  breaking the rounding or the accumulator fails 63 and 90 of its cases.
+
+### Changed
+
+- THEORY §1 and SCOPE §2.1 described `extract` as built on `F.unfold`, which
+  had been true only at dilation above 1 since 0.3.0 and is not true at all
+  now. Both describe the strided view and the copy. THEORY §9.1 and §9.2,
+  GUIDE §3, USAGE §5, the three READMEs and ADR 0004 state the integer
+  contract.
+
+## [0.5.6] - 2026-10-10
+
+A fix release. `torch.vmap` works again over `extract`, `reconstruct` and
+`stitch`, which it had not since 0.5.0, and `tilings` returns `[]` for an
+image smaller than the default minimum patch instead of raising. No other
+returned value changes. The full suite passes on both code paths at the
+declared floor (Python 3.12, torch 2.6.0, numpy 1.26.0, pillow 10.1.0, Rust
+1.82) and at the newest releases (Python 3.14, torch 2.14.1, numpy 2.5.4,
+pillow 12.3.0), and the 126,736-geometry exactness sweep passes on both paths.
+The rest is documentation, a CI job that now holds the floor to that claim,
+and the CI actions moved to Node 24.
+
+### Added
+
+- `docs/PAPER/`, the scaffold of an article on computing a mean whose every
+  intermediate stays in the input's domain, drawing on PatchCraft's
+  patch-grid mean: outline, formal statements with proofs, measurements with
+  the scripts that reproduce them, and checked references. It is not
+  documentation of the library and does not ship: `MANIFEST.in` prunes it and
+  `tools/check_dist.py` fails a release that carries it.
+- **CI tests the declared floor, not only the newest versions.** A new job
+  builds the extension with Rust 1.82 and runs the whole suite on both code
+  paths at Python 3.12, torch 2.6.0, numpy 1.26.0 and pillow 10.1.0, the
+  oldest versions `pyproject.toml` and `Cargo.toml` accept that install on
+  3.12; until now the floor was a claim no job exercised. The lock moves to
+  the newest runtime releases (torch 2.14.1, torchvision 0.29.1, numpy
+  2.5.4), so the other jobs test the top of the range; the development tools
+  stay pinned. The first run at the floor found one claim that held only at
+  the top: `extract` on an integer tensor raises torch's own error, which is a
+  `RuntimeError` at torch 2.6 and its subclass `NotImplementedError` in newer
+  releases, while the test, THEORY §9.1 and the PyPI page named the subclass.
+  They now name what holds across the range.
+- ADR 0005 is recorded in the ROADMAP as the 1.1 candidate, not scheduled.
+- ADR 0005 (`Proposed`) records how a grid that does not cover the image
+  would be padded, borrowed rather than designed: kornia's auto-padding on the
+  way in and unpadding on the way back, MONAI's `padding_mode` with `F.pad`'s
+  values, the padding split between both sides, and `None` as the default
+  that changes no call. Nothing is implemented. The survey and the
+  measurements behind it are in `docs/STUDIES/2026-10-10-border-policy.md`,
+  reproduced by `tools/compare_border_strategies.py`.
+- **THEORY §2.6 states the operator behind `reconstruct` and `stitch`.**
+  `extract` is a selection matrix `U`, the fold is `Uᵀ`, `UᵀU` is the count
+  map, `reconstruct` is the least-squares inverse `(UᵀU)⁻¹Uᵀ` and `stitch` the
+  window-weighted one, the same weighted overlap-add that inverts an STFT.
+  `tests/test_operator.py` pins each statement on both code paths. GUIDE
+  gains three recipes built on it, run against 0.5.5: what averaging does to a
+  per-patch quantization (§2), a filter applied per tile with a halo, which
+  comes back bit-identical to the whole-image filter (§5), and the padded
+  round trip for a frame no tiling covers (§6). Section 6 used to rule
+  padding out because it puts pixels the frame never had into the edge
+  patches; it now offers it with that cost stated.
+
+### Fixed
+
+- **`torch.vmap` works again over `extract`, `reconstruct` and `stitch`.** The
+  documentation names vmap as one of the three ways to batch (README, SCOPE,
+  USAGE, THEORY §0 and §9.1), and since 0.5.0 it failed on most calls: `extract`
+  at every geometry without dilation and `reconstruct` at `stride ==
+  patch_size` asked the tensor for its storage to guard against aliasing, which
+  a vmap batched tensor does not have, and with the accelerator every
+  overlapping `reconstruct` and `stitch` failed reading a data pointer. Both
+  guards are now an unconditional clone, which is the one copy those paths
+  always made, and the accelerator treats a tensor without storage as
+  ineligible and hands it to the torch path, as its docstring already said.
+  Bit-identical to 0.5.5 on ordinary calls in 144 comparisons per path,
+  including the degenerate geometries the guard existed for, with no output
+  sharing memory with its input and no change in time. `tests/test_vmap.py`
+  pins vmap to a plain loop bit for bit, on both paths and in four dtypes; 70
+  of its 114 cases fail against 0.5.5. The test helper `bit_equal` gained
+  bfloat16.
+- **`tilings` returns `[]` for an image smaller than the default minimum
+  patch.** A one-row image raised `min_patch_size (2) > max_patch_size (1)`,
+  blaming a bound the caller never passed, while THEORY §9.6 accepts any
+  positive shape and an explicit bound that excludes every patch already
+  returned `[]`. An explicit `max_patch_size` below `min_patch_size` still
+  raises. The docstring no longer promises at least one entry, which was false
+  for both cases.
+
+### Changed
+
+- **CI actions moved off Node 20**, which GitHub has deprecated and was
+  forcing onto Node 24: `actions/checkout` v5, `astral-sh/setup-uv` v7,
+  `actions/upload-artifact` v6, `actions/download-artifact` v7 and
+  `softprops/action-gh-release` v3, each the first major on Node 24 rather
+  than the newest. Every input the workflows pass exists in those versions.
+- **USAGE walks a 4×4 image through every call.** Its sections now show
+  the pixels, not only the shapes: the patches `extract` returns and their
+  order, where each patch lands in `reconstruct`, the per-pixel mean when
+  patches disagree, the step `uniform` leaves and the ramp `hann` and
+  `gaussian` make, an LR patch beside its HR patch in `pair`, a resize down
+  and back up, and the one patch `per_patch_mse` singles out. Every example
+  runs as a doctest. GUIDE §1 shows the uncovered band on a 5×5 count map, and
+  GUIDE §4 shows the count map beside the pixels that come back different.
+- GUIDE §4 still gave the old reason for the exactness rule, that division by
+  a power of two is exact; it now gives the corrected one, as the other pages
+  do since the entry below.
+- **The stated reason for the exactness rule is corrected.** The pages said the
+  round trip is exact because dividing a float by a power of two never rounds.
+  That leaves out the sum: k equal values added one at a time and divided by k
+  come back exact for k = 2 and 4, and for k = 8 they do not, since 3x, 5x, 6x
+  and 7x round (3,914,684 of the 8,388,608 float32 values in [1, 2) fail,
+  `python docs/PAPER/experiments/float_mean.py`). The rule itself stands,
+  because a coverage of three on either axis puts a 3 in the map, so over all
+  126,736 legal geometries a map of powers of two holds only 1, 2 and 4. The
+  READMEs, THEORY §1, the `reconstruct` docstring, ADR 0003 (with a dated
+  correction) and the outreach sources now give that reason.
+- Exact inside the rule means equal as values, which is what `torch.equal`
+  checks, and THEORY and the `reconstruct` docstring now say so: the fold sums
+  into `+0.0`, so on an overlapping grid a `-0.0` comes back `+0.0` and a NaN
+  may change its bits. Both paths do the same, and a test now pins it, which
+  `torch.equal` could not.
+- THEORY §9.2 said promotion cut the bfloat16 error from 9.3e-03 to 1.9e-03.
+  Those two numbers measured the input's cast from float32, not the library:
+  on data drawn in bfloat16 the native fold misses by 7.8e-03 and the promoted
+  round trip returns the input bit for bit, at counts 3, 6 and 9. THEORY,
+  GUIDE and the code comment now say so, and a test pins it.
+- THEORY §2 and §2.5 and USAGE §5 described the `reconstruct` and `stitch`
+  implementation from before 0.5.0 (a second fold of ones, a floor on every
+  denominator). They now describe the closed-form count map, the separable
+  window denominator and the non-overlapping rearrangement. USAGE §5 checks
+  the overlapping round trip with `torch.equal` instead of `torch.allclose`.
+- THEORY §9.6 said `tilings` returns a sorted list. Its order is patch size
+  ascending with the exact tile first, which `sorted()` does not give, and a
+  test now pins it.
+- The accelerator parity tests compare bits instead of `torch.equal`, and
+  include `stride == patch_size`, where hann and gaussian still fold now that
+  uniform takes the fast path.
+- Errata for 0.5.5, whose entry says it "changes no bit": that holds for
+  returned values in eager mode. Under the uniform window at `stride ==
+  patch_size`, derivatives pass a `-0.0` or a signaling NaN through unchanged
+  and `torch.compile` folds the `+ 0.0` away; the code comment now says so.
+- **Documentation that said more than the code does.** GUIDE called hann the
+  cheapest window, where on an overlapping grid the three cost the same; GUIDE
+  and the PyPI page said `extract` hands every tensor to `F.unfold`, where only
+  an integer one goes there; PERFORMANCE said 25 runs where the benchmark
+  takes 15; GUIDE's two bound figures now read as the measured misses inside
+  the `(k+1)·eps·|v|` bound, with the shape of the fp16 example stated.
+  FOCO-1.0 freezes values rather than bits, the bound rather than "1 ULP",
+  and 20 names. CONTRIBUTING and AGENTS name the three version strings a
+  release bumps, STATUS among them. The CITATION abstract no longer carries
+  development history, and the BibTeX author reads `Marques de Souza`.
+- `tools/compare_exactness_rules.py` also reports the worst miss outside the
+  rule: 19.0 ULP in float32, at `(h, w, ph, pw, sh, sw) = (18, 23, 9, 9, 1,
+  1)`, on a pixel covered 81 times. CI's ruff step checks `tools/` as well.
+- Outreach: a news source dated 2026-10-10 carries the 0.5.5 table, and the
+  2026-09-04 one stays as the record of 0.5.4. The articles follow it, scope
+  the 19 ULP figure to the geometry that produced it, and say where each path
+  was executed instead of calling the GPU path correct. The post no longer
+  says `extract` validates the geometry, the MNIST page states when each of
+  the three problems appears, and every reproduction block clones the
+  repository, since the wheel carries neither `tools/` nor `tests/`.
+
 ## [0.5.5] - 2026-09-26
 
 A performance release that changes no bit. Every change to `src/` below was
@@ -1016,7 +1207,9 @@ First public release. Public API stable; signatures will only change in 1.x.
 - [`README.md`](README.md) covers installation, the car-vs-track metaphor,
   validation lab.
 
-[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.5...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.7...HEAD
+[0.5.7]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.7
+[0.5.6]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.6
 [0.5.5]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.5
 [0.5.4]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.4
 [0.5.3]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.3

{patchcraft-0.5.5 → patchcraft-0.5.7}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - given-names: Leonardo
     family-names: Marques de Souza
     email: leonardo.marques.souza@gmail.com
-version: "0.5.5"
-date-released: "2026-09-26"
+version: "0.5.7"
+date-released: "2026-10-10"
 repository-code: "https://github.com/LeoPR/PatchCraft"
 license: MIT
 abstract: >
@@ -28,10 +28,9 @@ abstract: >
   every value of the overlap coverage map is a power of two, always true at
   stride equal to patch size, and outside that rule the per-pixel error is
   bounded by (k+1) times eps times the absolute value, with k the pixel's
-  coverage count. An earlier and weaker form of that claim was published, then
-  measured false and publicly retracted; a falsification suite now enumerates
-  the 126,736 legal geometries of the space independently of the predicate and
-  tries to break both halves of it.
+  coverage count. A falsification suite enumerates the 126,736 legal
+  geometries of the space independently of the predicate and tries to break
+  both halves of it.
 
   Five of the six published wheels carry a Rust kernel for the overlapping
   fold, compiled into the wheel itself rather than into a separate package, and

{patchcraft-0.5.5 → patchcraft-0.5.7}/CONTRIBUTING.md

@@ -34,7 +34,7 @@ is silently inert here. Either make that global hook delegate, or set
 whatever else the global hooks were doing.
 
 `ruff-format` is deliberately not among the hooks. This project has never used
-it, and adopting it would reformat 37 of 82 files in a commit that changed no
+it, and adopting it would reformat 37 files in a commit that changed no
 behaviour.
 
 ```
@@ -153,7 +153,7 @@ PatchCraft/
 │   ├── ISSUE_TEMPLATE/             four forms and a chooser; the required fields are what makes a report reproducible
 │   ├── PULL_REQUEST_TEMPLATE.md    asks whether a returned value moved, which decides the version bump
 │   └── workflows/
-│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated job
+│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated and floor jobs
 │   └── release.yml                 publishes to PyPI on vX.Y.Z tag push (Trusted Publishing)
 ├── src/patchcraft/                 library core, one-image-at-a-time primitives
 │   ├── __init__.py                 re-exports the full public API and the generated version
@@ -207,11 +207,12 @@ PatchCraft/
 │   ├── FOCO-1.0.md                 what 1.0 freezes, and the six blockers, all closed
 │   ├── ADR/                        one file per decision; the choice only, evidence in STUDIES/
 │   ├── STUDIES/                    background reading behind those decisions
-│   └── design/                     one spec per work phase: the alternatives measured and the decision
+│   ├── design/                     one spec per work phase: the alternatives measured and the decision
+│   └── PAPER/                      an article in preparation, with its experiments; not shipped
 ├── outreach/                       material for presenting the project publicly, not shipped
 │   ├── README.md                   how it is organized and what to check before publishing
-│   ├── 2026-09-04-lancamento.md    the current dated news source the channel texts derive from
-│   ├── 2026-09-03-lancamento.md    the previous one, kept as the record of 0.5.1
+│   ├── 2026-10-10-lancamento.md    the current dated news source the channel texts derive from
+│   ├── 2026-09-0*-lancamento.md    the earlier ones, kept as the records of 0.5.4 and 0.5.1
 │   └── linkedin/                   post, artigo, the illustrated page and the figures, PT and EN
 └── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
 ```
@@ -347,7 +348,7 @@ silent: a version that walks backwards rather than an error.
 ## Releasing (maintainer only)
 
 1. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
-2. Update `version` and `date-released` in [`CITATION.cff`](CITATION.cff), and the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. Those are the only version strings left in the repository, because a citation needs a concrete one. `uvx --from cffconvert cffconvert --validate` checks the file.
+2. Update `version` and `date-released` in [`CITATION.cff`](CITATION.cff), the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9, and the release named at the top of [`STATUS.md`](STATUS.md). Those are the version strings a release bumps, because a citation needs a concrete one and a snapshot names its release; [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) names the version it measured and changes only when the table is re-measured. `uvx --from cffconvert cffconvert --validate` checks the file.
 3. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
 4. Commit: `release: vX.Y.Z`.
 5. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.

{patchcraft-0.5.5 → patchcraft-0.5.7}/MANIFEST.in

@@ -42,3 +42,7 @@ prune .vscode
 # Presentation material, not source. It is tracked, so the file finder offers
 # it and only this line keeps it out.
 prune outreach
+# An article in preparation, not documentation of the library. Without this
+# line its experiment scripts would ship too, since the finder offers every
+# tracked file.
+prune docs/PAPER

{patchcraft-0.5.5 → patchcraft-0.5.7}/MAP.md

@@ -44,6 +44,7 @@ PatchCraft/
 ├── tests/ .................... the contract, executable
 │   ├── test_exactness.py ..... enumerates 126,736 geometries and tries to FALSIFY the predicate
 │   ├── test_reference.py ..... a naive loop the fast paths must agree with
+│   ├── test_operator.py ...... extract as a matrix U: the fold is U^T, reconstruct and stitch are least squares
 │   ├── test_public_api.py .... freezes the 20 names, their signatures and carrier fields
 │   └── _rng.py ............... audited data generation; integer ramps hid a real defect once
 │
@@ -58,12 +59,14 @@ PatchCraft/
 │   ├── FOCO-1.0.md ........... what 1.0 freezes, and the six blockers, all closed
 │   ├── ADR/ .................. one file per decision; the choice, not the research
 │   ├── design/ ............... one spec per work phase: alternatives measured, then chosen
-│   └── STUDIES/ .............. background reading, and the Strata conformity review
+│   ├── STUDIES/ .............. background reading, and the Strata conformity review
+│   └── PAPER/ ................ an article in preparation, on means that stay in their domain; not shipped
 │
 ├── tools/
 │   ├── benchmark.py .......... accelerated vs pure, and proves they agree before timing
 │   ├── check_dist.py ......... release gate: extension present, versions agree, tag respected
 │   ├── compare_exactness_rules.py  the power-of-two rule against k_max <= 4, measured
+│   ├── compare_border_strategies.py  truncate, pad or move the last window, measured
 │   └── make_outreach_figures.py    every outreach figure and generated page, computed
 │
 ├── outreach/ ................. material for presenting the project; not shipped
@@ -82,6 +85,7 @@ PatchCraft/
 | **Work on it as an agent**, or learn what this repo insists on | [AGENTS.md](AGENTS.md) |
 | **Use it**: every argument, measured, with its printed output | [docs/GUIDE.md](docs/GUIDE.md) |
 | Know **when the round trip is exact**, as a rule I can evaluate myself | [docs/GUIDE.md §4](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit), and [docs/ADR/0003](docs/ADR/0003-reversibility-classes.md) for the contract |
+| Know **what `reconstruct` and `stitch` compute** for patches a model changed, and how to filter or pad around them | [docs/THEORY.md §2.6](docs/THEORY.md), then [docs/GUIDE.md](docs/GUIDE.md) §2, §5 and §6 for the measured recipes |
 | Know **what each function accepts and rejects**, precisely | [docs/THEORY.md §9](docs/THEORY.md), which is the arbiter where documents disagree |
 | Know **whether this library is the right tool** | [docs/SCOPE.md](docs/SCOPE.md) |
 | Know **what the native accelerator is worth**, and re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md), then `python tools/benchmark.py` |

{patchcraft-0.5.5/src/patchcraft.egg-info → patchcraft-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.5
+Version: 0.5.7
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT
@@ -111,7 +111,7 @@ blended = stitch(edited, image.shape, stride=16, weight="hann")
 assert blended.shape == image.shape                  # seams smoothed, geometry preserved
 ```
 
-PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` passes the tensor straight to `F.unfold`, and torch has no integer kernel there: it raises `NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'`.
+An 8-bit image goes in as it is. `extract` copies, so its patches hold the image's own bytes, and `reconstruct` returns them exactly in every legal geometry, since `k` copies of `v` sum to `k·v` and divide back to `v`; patches that disagree come back as their exact mean rounded half to even. `stitch` stays float-only, because its windows are float weights.
 
 ## reconstruct or stitch
 
@@ -128,7 +128,7 @@ Uniform averaging is the default, and it is the option that reports what the mod
 
 ## Why not unfold and fold directly
 
-Nothing stops you, and PatchCraft is a thin contract over exactly those two calls. What the contract buys is the pixel order and the boundary checks, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
+Nothing stops you. What PatchCraft adds is the pixel order and the boundary checks, done once with tests around them, and a faster fold where the wheel carries one, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
 
 ```python
 import torch
@@ -144,7 +144,7 @@ assert scrambled.shape == patches.shape                      # the right shape
 assert not torch.equal(scrambled, patches)                   # and the wrong pixels
 ```
 
-The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agreed to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
+The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window costs 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agree to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
 
 ## The geometry has to cover the image
 
@@ -162,9 +162,9 @@ It helps when you tile one image for an inference pass too large to run in a sin
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two. The reason is that reconstruction divides each pixel by the number of patches that covered it, and dividing a float by a power of two is the one division that never rounds.
+The round trip of a float image is exact when every value in the count map is a power of two. Reconstruction adds up the patches covering each pixel and divides by how many there were, and in a legal geometry a map of powers of two holds only the counts 1, 2 and 4, where both steps are exact: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4.
 
-That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness.
+That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness. An integer image comes back exact in every legal geometry, because integer sums do not round.
 
 The everyday shorthand is that `stride == patch_size` and `stride == patch_size / 2` always satisfy the rule. Both are sufficient conditions rather than necessary ones, so a geometry outside them can still be exact, and the [guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) carries the sweep that measures it.
 
@@ -178,7 +178,7 @@ Where it applies today: on GPU the functions accept CUDA tensors and keep the de
 
 - [Guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), the manual, with every figure on this page shown as runnable code
 - [Performance](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md), what the native accelerator is worth and how to re-measure it
-- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 20 public symbols, executed as a doctest
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of the public surface, executed as a doctest
 - [Theory](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md), the math and the per-function contract
 - [Scope](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md), the line between this library and your pipeline
 - [Repository](https://github.com/LeoPR/PatchCraft), [issues](https://github.com/LeoPR/PatchCraft/issues) and [contributing](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md)

{patchcraft-0.5.5 → patchcraft-0.5.7}/README.md

@@ -83,7 +83,7 @@ The two functions answer two different questions, so choosing between them is th
 
 | You want | Call | Because |
 |---|---|---|
-| The patches back as an image, untouched | `reconstruct` | Exact inverse of `extract` when every overlap count is a power of two, which is always true at `stride == patch_size` |
+| The patches back as an image, untouched | `reconstruct` | Exact inverse of `extract`: always for an integer image, and for a float image when every overlap count is a power of two, which is always true at `stride == patch_size` |
 | A model's output back as an image | `stitch` | Overlapping patches disagree, and the window hides the grid |
 
 ## Why not unfold and fold directly
@@ -140,13 +140,13 @@ PatchCraft does not help when you want a batched op over N images, a dataset or
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two, which happens because dividing a float by a power of two is the one division that never rounds. Outside that rule the per-pixel error is bounded by (k+1)·eps·|v|, with k the pixel's coverage count. A wider float buys a smaller miss and never exactness, so float64 is not a safe harbour. The axis that decides the answer is the geometry and not the dtype, and [the guide](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) has the sweep that measures it.
+The round trip of a float image is exact when every value in the count map is a power of two, which in a legal geometry means every count is 1, 2 or 4: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4. Outside that rule the per-pixel error is bounded by (k+1)·eps·|v|, with k the pixel's coverage count. A wider float buys a smaller miss and never exactness, so float64 is not a safe harbour: among floats the axis that decides the answer is the geometry, and [the guide](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) has the sweep that measures it. An integer image comes back exact in every legal geometry, because integer sums do not round.
 
 ## Status
 
 **Pre-1.0**, and the badge above is the current release. While the leading digit is zero the middle one is the compatibility boundary, so `0.y.z` is safe to take and a new `0.y` is where an output value or a signature is allowed to move. [CHANGELOG.md](CHANGELOG.md) records every such change with the measurement behind it.
 
-1657 tests collected and CI is green on {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, with `ruff check` and `mypy --strict` in the same run. The package is typed and ships `py.typed`.
+CI is green on {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14} with the newest torch, and on the declared floor, Python 3.12 with torch 2.6, numpy 1.26, pillow 10.1 and Rust 1.82, with `ruff check` and `mypy --strict` in the same run. The package is typed and ships `py.typed`.
 
 On GPU the functions keep the device you hand them, and the Rust kernel is CPU-only, so it does not accelerate there; every figure here is a CPU figure. No external project consumes the library yet, which is the gate for calling the API settled. [The guide](docs/GUIDE.md#8-where-this-applies-today) says where the rest applies.
 
@@ -156,7 +156,7 @@ On GPU the functions keep the device you hand them, and the Rust kernel is CPU-o
 |---|---|
 | The manual: every argument above, measured, with its output | [docs/GUIDE.md](docs/GUIDE.md) |
 | What the native accelerator is worth, and how to re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) |
-| A walkthrough of each of the 20 public symbols, executed as a doctest | [docs/USAGE.md](docs/USAGE.md) |
+| A walkthrough of the public surface, executed as a doctest | [docs/USAGE.md](docs/USAGE.md) |
 | The line between this library and your pipeline | [docs/SCOPE.md](docs/SCOPE.md) |
 | The math, the decisions and the per-function contract | [docs/THEORY.md](docs/THEORY.md) |
 | Why the API looks like this | [docs/ADR/](docs/ADR) |

{patchcraft-0.5.5 → patchcraft-0.5.7}/README.pt-BR.md

@@ -83,7 +83,7 @@ O `stitch` é para patches que um modelo reescreveu. Nesse caso os patches vizin
 
 | Você quer | Chame | Porque |
 |---|---|---|
-| Os patches de volta como imagem, intocados | `reconstruct` | Inverso exato do `extract` quando toda contagem de sobreposição é potência de dois, o que sempre vale com `stride == patch_size` |
+| Os patches de volta como imagem, intocados | `reconstruct` | Inverso exato do `extract`: sempre para uma imagem inteira, e para uma imagem float quando toda contagem de sobreposição é potência de dois, o que sempre vale com `stride == patch_size` |
 | A saída de um modelo de volta como imagem | `stitch` | Patches sobrepostos discordam, e a janela esconde a grade |
 
 ## Por que não usar `unfold` e `fold` direto
@@ -106,7 +106,7 @@ assert scrambled.shape == patches.shape                      # a forma certa
 assert not torch.equal(scrambled, patches)                   # e os pixels errados
 ```
 
-O segundo é um stride que não cobre a imagem. Numa imagem de 128 por 128 com `patch=32, stride=20`, a grade para no pixel 112, o que deixa 3840 dos 16384 pixels em zero, e um `fold` escrito à mão devolve essa imagem parcialmente preta sem reclamar.
+O segundo é um stride, a distância de um patch para o próximo, que não cobre a imagem. Numa imagem de 128 por 128 com `patch=32, stride=20`, a grade para no pixel 112, o que deixa 3840 dos 16384 pixels em zero, e um `fold` escrito à mão devolve essa imagem parcialmente preta sem reclamar.
 
 Escrever o laço de recortar e remontar à mão custa 17 linhas não vazias contra 3 aqui, e os dois resultados concordam em cerca de 1,2e-05 num valor em [0, 1], mais de 300 vezes menos que um degrau de 8 bits, com as duas rotas diferindo só na ordem em que somam uma janela separável. [O manual](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) roda as duas versões lado a lado.
 
@@ -140,13 +140,13 @@ O PatchCraft não ajuda quando você quer uma operação em lote sobre N imagens
 
 ## Quando o round-trip é bit a bit
 
-O round-trip é exato quando todo valor do mapa de cobertura é potência de dois, e isso acontece porque dividir um float por uma potência de dois é a única divisão que nunca arredonda. Fora dessa regra, o erro por pixel é limitado por (k+1)·eps·|v|, com k a contagem de cobertura do pixel. Um float mais largo compra um erro menor e nunca a exatidão, então o float64 não é um porto seguro. Quem decide a resposta é a geometria, e não o dtype. [O manual](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) traz a varredura que mede isso.
+O round-trip de uma imagem float é exato quando todo valor do mapa de cobertura é potência de dois, o que numa geometria legal quer dizer que toda contagem é 1, 2 ou 4: somar duas ou quatro cópias de um valor nunca arredonda, e dividir por 2 ou por 4 também não. Fora dessa regra, o erro por pixel é limitado por (k+1)·eps·|v|, com k a contagem de cobertura do pixel. Um float mais largo compra um erro menor e nunca a exatidão, então o float64 não é um porto seguro: entre os floats, quem decide a resposta é a geometria, e [o manual](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) traz a varredura que mede isso. Uma imagem inteira volta exata em toda geometria legal, porque soma de inteiros não arredonda.
 
 ## Estado
 
 **Pré-1.0**, e o badge acima mostra a versão atual. Enquanto o primeiro dígito for zero, quem marca a fronteira de compatibilidade é o do meio: um `0.y.z` novo é seguro de pegar, e é num `0.y` novo que um valor de saída ou uma assinatura pode mudar. O [CHANGELOG.md](CHANGELOG.md) registra cada uma dessas mudanças com a medição por trás dela.
 
-São 1657 testes coletados, com CI verde em {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, e com `ruff check` e `mypy --strict` na mesma execução. O pacote é tipado e distribui o `py.typed`.
+A CI está verde em {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14} com o torch mais novo, e no piso declarado, Python 3.12 com torch 2.6, numpy 1.26, pillow 10.1 e Rust 1.82, com `ruff check` e `mypy --strict` na mesma execução. O pacote é tipado e distribui o `py.typed`.
 
 Em GPU as funções preservam o dispositivo que você passa, e o kernel Rust é só de CPU, então não acelera ali; todo número desta página é de CPU. Nenhum projeto externo consome a biblioteca ainda, que é o critério para dizer a API assentada. [O manual](docs/GUIDE.md#8-where-this-applies-today) diz onde o resto se aplica.
 
@@ -156,7 +156,7 @@ Em GPU as funções preservam o dispositivo que você passa, e o kernel Rust é
 |---|---|
 | O manual: cada argumento acima, medido, com a saída | [docs/GUIDE.md](docs/GUIDE.md) |
 | Quanto vale o acelerador nativo, e como remedir | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) |
-| Um passeio por cada um dos 20 símbolos públicos, executado como doctest | [docs/USAGE.md](docs/USAGE.md) |
+| Um passeio pela superfície pública, executado como doctest | [docs/USAGE.md](docs/USAGE.md) |
 | A linha entre esta biblioteca e o seu pipeline | [docs/SCOPE.md](docs/SCOPE.md) |
 | A matemática, as decisões e o contrato por função | [docs/THEORY.md](docs/THEORY.md) |
 | Por que a API tem essa cara | [docs/ADR/](docs/ADR) |

{patchcraft-0.5.5 → patchcraft-0.5.7}/README.pypi.md

@@ -69,7 +69,7 @@ blended = stitch(edited, image.shape, stride=16, weight="hann")
 assert blended.shape == image.shape                  # seams smoothed, geometry preserved
 ```
 
-PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` passes the tensor straight to `F.unfold`, and torch has no integer kernel there: it raises `NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'`.
+An 8-bit image goes in as it is. `extract` copies, so its patches hold the image's own bytes, and `reconstruct` returns them exactly in every legal geometry, since `k` copies of `v` sum to `k·v` and divide back to `v`; patches that disagree come back as their exact mean rounded half to even. `stitch` stays float-only, because its windows are float weights.
 
 ## reconstruct or stitch
 
@@ -86,7 +86,7 @@ Uniform averaging is the default, and it is the option that reports what the mod
 
 ## Why not unfold and fold directly
 
-Nothing stops you, and PatchCraft is a thin contract over exactly those two calls. What the contract buys is the pixel order and the boundary checks, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
+Nothing stops you. What PatchCraft adds is the pixel order and the boundary checks, done once with tests around them, and a faster fold where the wheel carries one, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
 
 ```python
 import torch
@@ -102,7 +102,7 @@ assert scrambled.shape == patches.shape                      # the right shape
 assert not torch.equal(scrambled, patches)                   # and the wrong pixels
 ```
 
-The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agreed to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
+The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window costs 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agree to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
 
 ## The geometry has to cover the image
 
@@ -120,9 +120,9 @@ It helps when you tile one image for an inference pass too large to run in a sin
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two. The reason is that reconstruction divides each pixel by the number of patches that covered it, and dividing a float by a power of two is the one division that never rounds.
+The round trip of a float image is exact when every value in the count map is a power of two. Reconstruction adds up the patches covering each pixel and divides by how many there were, and in a legal geometry a map of powers of two holds only the counts 1, 2 and 4, where both steps are exact: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4.
 
-That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness.
+That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness. An integer image comes back exact in every legal geometry, because integer sums do not round.
 
 The everyday shorthand is that `stride == patch_size` and `stride == patch_size / 2` always satisfy the rule. Both are sufficient conditions rather than necessary ones, so a geometry outside them can still be exact, and the [guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) carries the sweep that measures it.
 
@@ -136,7 +136,7 @@ Where it applies today: on GPU the functions accept CUDA tensors and keep the de
 
 - [Guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), the manual, with every figure on this page shown as runnable code
 - [Performance](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md), what the native accelerator is worth and how to re-measure it
-- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 20 public symbols, executed as a doctest
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of the public surface, executed as a doctest
 - [Theory](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md), the math and the per-function contract
 - [Scope](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md), the line between this library and your pipeline
 - [Repository](https://github.com/LeoPR/PatchCraft), [issues](https://github.com/LeoPR/PatchCraft/issues) and [contributing](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md)