patchcraft 0.5.6__tar.gz → 0.5.7__tar.gz

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

@@ -6,6 +6,45 @@ 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
@@ -1168,7 +1207,8 @@ 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.6...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

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

@@ -6,7 +6,7 @@ authors:
   - given-names: Leonardo
     family-names: Marques de Souza
     email: leonardo.marques.souza@gmail.com
-version: "0.5.6"
+version: "0.5.7"
 date-released: "2026-10-10"
 repository-code: "https://github.com/LeoPR/PatchCraft"
 license: MIT

{patchcraft-0.5.6 → patchcraft-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.6
+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` routes an integer tensor to `F.unfold`, and torch has no integer kernel there: it raises its own error, `"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
 
@@ -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. 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.
+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.
 

{patchcraft-0.5.6 → 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,7 +140,7 @@ 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 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. 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
 

{patchcraft-0.5.6 → 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
@@ -140,7 +140,7 @@ 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, 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. 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
 

{patchcraft-0.5.6 → 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` routes an integer tensor to `F.unfold`, and torch has no integer kernel there: it raises its own error, `"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
 
@@ -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. 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.
+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.
 

{patchcraft-0.5.6 → patchcraft-0.5.7}/STATUS.md

@@ -6,12 +6,12 @@
 
 ## Where the project is
 
-**0.5.6 is on PyPI**, published through Trusted Publishing on a tag push: one
+**0.5.7 is on PyPI**, published through Trusted Publishing on a tag push: one
 sdist, five `cp312-abi3` platform wheels carrying the Rust accelerator, and one
 universal `py3-none-any` wheel. There is no extra to enable and no second
 package.
 
-**1818 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
+**1971 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
 deselected, plus two full-sweep gates behind `PATCHCRAFT_SWEEP_FULL=1`
 that enumerate all 126,736 legal geometries. CI is green on
 {Ubuntu, Windows} x {3.12, 3.13, 3.14} on the pure path, plus a two-OS job that
@@ -24,7 +24,14 @@ pillow 10.1, Rust 1.82) that runs it on both paths.
 
 ## What is in flight
 
-**Nothing unreleased.** 0.5.6 is a fix release: `torch.vmap` over `extract`,
+**Nothing unreleased.** 0.5.7 brings integer images: `extract` takes every
+dtype, and `reconstruct` takes the five integer dtypes and returns them exactly
+in every legal geometry, with disagreeing patches rounded half to even and no
+intermediate overflowing. They are ADR 0004's steps 1 and 2, shipped together.
+The full suite and the 126,736-geometry sweep, which now includes an integer
+round trip, pass on both paths.
+
+0.5.6, the release before it, was a fix release: `torch.vmap` over `extract`,
 `reconstruct` and `stitch`, which the documentation offers as a way to batch,
 failed on most calls since 0.5.0 and works again, pinned by
 `tests/test_vmap.py`; and `tilings` returns `[]` for an image smaller than the
@@ -57,7 +64,9 @@ vocabulary its first draft proposed is deferred until a transform needs it.
 
 **ADR 0004 is `Proposed`, and asks nothing.** It records the precision and
 effort parameters as a design that is not built; the status reflects that none
-of it is implemented, not that a decision is pending. The one question it
+of the parameters is implemented, not that a decision is pending. Its steps 1
+and 2, integers through `extract` and `reconstruct` without a knob, are on
+`main` since 2026-10-10. The one question it
 appeared to hold, whether to add the knobs before the 1.0 freeze or after,
 rested on the premise that adding one afterwards is expensive. It is not: each
 is a keyword-only argument with a default, so adding one is additive and is a

{patchcraft-0.5.6 → patchcraft-0.5.7}/docs/ADR/0004-precision-and-effort-parameters.md

@@ -41,9 +41,11 @@ external consumer, and Strata §9's default verdict all point the same way.
 
 **So this ADR asks nothing.** It records a design that is not built, the names precedent
 determines, the constraint that would make a preset safe, and the order. It stays `Proposed`
-because none of it is implemented, not because a decision is pending.
+because none of its parameters is implemented, not because a decision is pending.
 
-**Nothing here is implemented.**
+**What is implemented is the integer path without a knob:** steps 1 and 2 below shipped
+together on 2026-10-10, ahead of the 1.0 the table assigned them to, because the owner moved
+them forward. None of the parameters exists.
 
 ## 1. The names, determined by precedent
 
@@ -146,8 +148,8 @@ this heading, was posed on top of a table that had already answered it.
 |---|---|---|---|
 | 0. Record this ADR, and qualify the four copies of "widening the dtype does not help" | 0.5 to 1 day | no | before 1.0, and it is the only item that must be |
 | A. Fix three defects as bugs, no knob | done, 2026-09-03 | no signature change | done before 1.0, as planned |
-| 1. `extract` accepts the five integer dtypes, by adding them to the fast-path set | ~1 day | no | after 1.0, never alone |
-| 2. Exact integer `reconstruct`, unrestricted, `int32` accumulator, every legal geometry | 4 to 6 days | no signature change | after 1.0, shipped with step 1 as one 1.1 |
+| 1. `extract` accepts the five integer dtypes, by adding them to the fast-path set | ~1 day | no | **done, 2026-10-10**, with step 2: every dtype now takes one strided-view path, at every dilation |
+| 2. Exact integer `reconstruct`, unrestricted, `int32` accumulator, every legal geometry | 4 to 6 days | no signature change | **done, 2026-10-10**, with step 1: an `int64` sum up to `int32` and a quotient-and-remainder split for `int64`, so nothing overflows; disagreeing patches round half to even, as `resize` does |
 | 3. Byte-native `uint8` quotient-and-remainder path | 2 to 3 days | no | do not build yet: 1.7x over an `int32` accumulator, at the cost of a second, different predicate on the doc surface |
 | 4. `accum_dtype=` on `reconstruct` and `stitch` | 1 day, 2 alongside step 2 | yes, signature | after 1.0 |
 | 5. `rounding_mode=` on `stitch` | 1 day | yes, signature | after 1.0, and only if a real caller appears |
@@ -206,5 +208,7 @@ only if one appears do the knobs follow, and the preset last of all.
    once: 0.2.1 added the `reconstruct` integer guard, turning a raw `NotImplementedError`
    into a framed `ValueError`.
 4. Integers with `dilation > 1`: a framed `ValueError`, or torch's raw error in that corner?
+   *Answered by the implementation, 2026-10-10:* neither. `extract` no longer goes through
+   `F.unfold`, so a dilated integer extraction is the same strided copy as any other.
 5. CUDA. Everything here was measured on CPU, and the accelerator refuses non-CPU tensors
    outright. No accept text may say "integers work" without a device qualifier.

{patchcraft-0.5.6 → patchcraft-0.5.7}/docs/GUIDE.md

@@ -328,38 +328,44 @@ There are three ways out, depending on what you need. Decide once for the whole
 
 ## 3. Dtypes and files
 
-### Float tensors only
+### Integer images
 
-`extract` routes an integer tensor to `F.unfold`, which has no integer kernel, so an 8-bit image fails with torch's own message rather than with one of ours. Convert on the way in, which costs you one division.
+`extract` copies, so an 8-bit image goes in as it is and its patches are the image's own bytes. `reconstruct` takes them back in every legal geometry, and for integers there is no count-map rule: `k` copies of `v` sum to `k·v` exactly, and `k·v` divided by `k` is `v`. The example uses patch 3 at stride 1, whose counts of 3, 6 and 9 make the float round trip inexact ([section 4](#4-when-the-round-trip-is-bit-for-bit)).
 
 ```python
 import torch
-from patchcraft import extract, reconstruct
+from patchcraft import extract, reconstruct, stitch
 
-eight_bit = (torch.rand(1, 64, 64) * 255).to(torch.uint8)   # what read_image or PIL gives you
-try:
-    extract(eight_bit, patch_size=16, stride=16)
-except Exception as error:
-    print("extract:", type(error).__name__ + ":", error)
+torch.manual_seed(0)
+eight_bit = torch.randint(0, 256, (1, 64, 64), dtype=torch.uint8)   # what read_image or PIL gives you
+patches = extract(eight_bit, patch_size=3, stride=1)
+back = reconstruct(patches, eight_bit.shape, stride=1)
+print(tuple(patches.shape), patches.dtype, "| round trip exact:", torch.equal(back, eight_bit))
 
-patches = extract(eight_bit.float() / 255, patch_size=16, stride=16)
-print(tuple(patches.shape), patches.dtype)
+as_float = eight_bit.float() / 255
+back_float = reconstruct(extract(as_float, patch_size=3, stride=1), as_float.shape, stride=1)
+print("the same geometry in float32, exact:", torch.equal(back_float, as_float))
+
+# Two 1x2 patches that disagree on the middle pixel of a 1x3 strip.
+two = torch.tensor([[[[10, 11]]], [[[12, 20]]]], dtype=torch.uint8)
+print("11 and 12 on the middle pixel:", reconstruct(two, (1, 1, 3), stride=1)[0, 0].tolist())
 
 try:
-    reconstruct(patches.to(torch.uint8), (1, 64, 64), stride=16)
-except Exception as error:
-    print("reconstruct:", type(error).__name__ + ":", error)
+    stitch(patches, eight_bit.shape, stride=1, weight="hann")
+except ValueError as error:
+    print("stitch:", str(error).split(". ")[0])
 ```
 
 ```
-extract: NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'
-(16, 1, 16, 16) torch.float32
-reconstruct: ValueError: reconstruct requires floating-point patches, got dtype=torch.uint8. F.fold is not implemented for integer dtypes; convert with patches.float() first.
+(3844, 1, 3, 3) torch.uint8 | round trip exact: True
+the same geometry in float32, exact: False
+11 and 12 on the middle pixel: [10, 12, 20]
+stitch: stitch requires floating-point patches, got dtype=torch.uint8
 ```
 
-The two messages are not equally good, and the asymmetry is a rough edge rather than a design. `reconstruct` and `stitch` carry a dtype guard that raises a framed `ValueError` naming the conversion, while `extract` still lets torch's raw `NotImplementedError` through.
+Patches that disagree, which is what a model returns, come back as the exact mean rounded half to even, the rounding `resize` already applies to integers: 11 and 12 give 12, and so would 12 and 13. Nothing overflows on the way, `int64` included, because up to `int32` the sum lives in `int64`, and `int64` values are divided by their pixel's count before they are added.
 
-The accepted dtypes are `float16`, `float32`, `float64` and `bfloat16`, and they are contract text in [THEORY.md](THEORY.md) §9.1 and §9.2.
+`stitch` stays float-only, since its windows are float weights and a weighted mean of integers would have to round somewhere you should choose. `reconstruct` refuses `bool`, because a mean of booleans is a vote. The accepted dtypes are contract text in [THEORY.md](THEORY.md) §9.1 and §9.2, measured on CPU.
 
 ### End to end from a file
 
@@ -959,7 +965,7 @@ The LR and HR pairing symbols, which are `pair`, `paired_tilings` and `scale_fac
 
 **Before 1.0, and with no external consumer yet.** A real project consuming the published API is the gate [ROADMAP.md](ROADMAP.md) sets for calling the shape settled. Until then a new `0.y` may still change what comes out; pin `~=0.5.0` to take fixes only.
 
-What is verified is this. The full local run of `pytest -m "not gpu"` passes 1818 tests, skips 32 cases, and deselects 5 GPU tests, in under a minute on this machine, so run `pytest` yourself for the number in your environment. Of those skips, 30 are geometries that do not cover exactly and 2 are the full 126,736-geometry sweep, which is a local gate you arm with `PATCHCRAFT_SWEEP_FULL=1`. CI runs the same suite plus `ruff check` and `mypy --strict` on Ubuntu and Windows against Python 3.12, 3.13 and 3.14, and all six cells are green. Those six are forced onto the pure-torch path, so a separate two-cell job on Ubuntu and Windows builds the Rust kernel and runs the whole suite through it. Those eight run the newest torch, and one more job runs the whole suite on both paths at the declared floor: Python 3.12, torch 2.6, numpy 1.26 and pillow 10.1, with the kernel built by Rust 1.82. Releases reach PyPI through Trusted Publishing on a tag push. The package is typed and it ships `py.typed`.
+What is verified is this. The full local run of `pytest -m "not gpu"` passes 1971 tests, skips 32 cases, and deselects 5 GPU tests, in under a minute on this machine, so run `pytest` yourself for the number in your environment. Of those skips, 30 are geometries that do not cover exactly and 2 are the full 126,736-geometry sweep, which is a local gate you arm with `PATCHCRAFT_SWEEP_FULL=1`. CI runs the same suite plus `ruff check` and `mypy --strict` on Ubuntu and Windows against Python 3.12, 3.13 and 3.14, and all six cells are green. Those six are forced onto the pure-torch path, so a separate two-cell job on Ubuntu and Windows builds the Rust kernel and runs the whole suite through it. Those eight run the newest torch, and one more job runs the whole suite on both paths at the declared floor: Python 3.12, torch 2.6, numpy 1.26 and pillow 10.1, with the kernel built by Rust 1.82. Releases reach PyPI through Trusted Publishing on a tag push. The package is typed and it ships `py.typed`.
 
 Where the evidence is thinner, this is what it means for you.
 
@@ -1012,7 +1018,7 @@ Installing from the sdist compiles the accelerator when a Rust toolchain is pres
   author  = {Marques de Souza, Leonardo},
   title   = {PatchCraft: image patch extraction, reconstruction, pairing
              and seam-aware stitching},
-  version = {0.5.6},   % check CHANGELOG.md for the release you used
+  version = {0.5.7},   % check CHANGELOG.md for the release you used
   year    = {2026},
   url     = {https://github.com/LeoPR/PatchCraft}
 }

{patchcraft-0.5.6 → patchcraft-0.5.7}/docs/SCOPE.md

@@ -57,13 +57,12 @@ inside the primitive.
 
 ### 2.1 Inside `extract`: torch already does it
 
-`extract(image, ...)` reduces to a single `torch.nn.functional.unfold`
-call. There is no Python loop over patches. The work happens in:
+`extract(image, ...)` reduces to one strided window view of the image and
+one copy. There is no Python loop over patches. The view costs nothing, and
+the copy is a single tensor operation over the whole `(C, H, W)` image:
 
-- **CPU**: `im2col` is a vectorized C++ implementation; uses SIMD where
-  applicable. Operates on the whole `(C, H, W)` tensor at once.
-- **CUDA**: a single `im2col` kernel launch. Patches are produced in
-  parallel across thousands of CUDA threads.
+- **CPU**: one vectorized copy kernel, which torch runs on its own thread pool.
+- **CUDA**: one copy kernel launch, parallel across the device.
 
 You get the parallelism for free; PatchCraft does not need to and does
 not try to.

{patchcraft-0.5.6 → patchcraft-0.5.7}/docs/THEORY.md

@@ -28,9 +28,9 @@ Multi-image batching is **out of scope**, not under-specified: callers use a Pyt
 
 **Boundary conditions.** Truncation, never padding. Pixels in the trailing rows/columns that do not fit a full patch are dropped. PatchCraft does not synthesize data; callers who need full coverage should pad the image themselves before extracting.
 
-**Memory layout.** `F.unfold(x.unsqueeze(0), (ph,pw), dilation=d, stride=(sh,sw))` yields shape `(1, C·ph·pw, L)`. Reshape as `.view(C, ph, pw, L).permute(3, 0, 1, 2).contiguous()` to obtain `(L, C, ph, pw)`. Device and dtype are preserved from the input.
+**Memory layout.** `F.unfold(x.unsqueeze(0), (ph,pw), dilation=d, stride=(sh,sw))` yields shape `(1, C·ph·pw, L)`, and the layout to get from there to `(L, C, ph, pw)` is `.view(C, ph, pw, L).permute(3, 0, 1, 2).contiguous()`; the intuitive `.view(L, C, ph, pw)` keeps the shape and scrambles the pixels. `extract` does not go through `F.unfold`: it takes the strided window view `x.unfold(1, eh, sh).unfold(2, ew, sw)` over the dilated footprint, keeps every `d`-th pixel of it, and copies once into `(L, C, ph, pw)`. Device and dtype are preserved from the input.
 
-**Design decision.** `patchcraft.extract(image, patch_size, stride, dilation=1) -> Tensor[L, C, ph, pw]` is a pure function built on `F.unfold`. `image` must be `(C, H, W)`; batching is explicit (call in a loop or `vmap`) and is not part of the v0.1 signature. `patch_size` and `stride` accept `int` (square) or `(int, int)`. Truncation is the only boundary policy. When no patch fits, we return an empty tensor `Tensor[0, C, ph, pw]` rather than raising, so callers decide. No caching inside the function; caching is a separate concern (see §4). Dilation is supported here even though reconstruction rejects it (see §2). See also [ADR 0001](ADR/0001-patch-extraction-api.md) for the API rationale.
+**Design decision.** `patchcraft.extract(image, patch_size, stride, dilation=1) -> Tensor[L, C, ph, pw]` is a pure function built on a strided window view of the image and one copy, which has a kernel for every dtype. `image` must be `(C, H, W)`; batching is explicit (call in a loop or `vmap`) and is not part of the v0.1 signature. `patch_size` and `stride` accept `int` (square) or `(int, int)`. Truncation is the only boundary policy. When no patch fits, we return an empty tensor `Tensor[0, C, ph, pw]` rather than raising, so callers decide. No caching inside the function; caching is a separate concern (see §4). Dilation is supported here even though reconstruction rejects it (see §2). See also [ADR 0001](ADR/0001-patch-extraction-api.md) for the API rationale.
 
 **Composability with torch transforms (Patchify).** ADR 0002 adds a thin callable companion: `patchcraft.Patchify(patch_size, stride, dilation=1)` is a class with `__call__(image) -> Tensor[L, C, ph, pw]` that delegates to `extract`. It exists to slot into `torchvision.transforms.Compose([..., Patchify(4, 2), ...])` without forcing callers to write a lambda, because lambdas are not repr-friendly and they skip eager validation. `Patchify` validates the geometry in `__init__` (so a bad `patch_size` fails when the pipeline is built, not when the first batch arrives), and carries **only** the geometry ints (`__slots__`, no `__dict__`, no cache, no buffer). The function is the contract; the class is a convenience. Same shape contract, same dtype/device preservation, same truncation policy.
 
@@ -260,9 +260,9 @@ Esta seção consolida, por API, as condições que v0.1 deve **aceitar**, **rej
 `Patchify(...)(image)` is the callable form and delegates to `extract` with the same contract, plus eager geometry validation at `__init__`.
 
 **Aceita:**
-- `image` é `Tensor` 3D `(C, H, W)` com `C ≥ 1` arbitrário; dtype suportado por `torch.nn.functional.unfold` (todos os float: `float16/float32/float64/bfloat16`); CPU ou CUDA (preservados na saída).
+- `image` é `Tensor` 3D `(C, H, W)` com `C ≥ 1` arbitrário, de **qualquer dtype**: os float, os cinco inteiros (`uint8`, `int8`, `int16`, `int32`, `int64`), `bool` e os complexos, em qualquer `dilation`. CPU ou CUDA (preservados na saída).
 
-  Em CPU, **nenhum** dtype inteiro funciona: `im2col_out_cpu` não é implementado para `Byte`, `Int` nem `Long` (verificado em torch 2.13.0+cpu). Uma versão anterior desta seção dizia que só `uint8` era o problema; está errado. O caller converte pra float antes. `extract` não intercepta isso, então o erro que sobe é o do próprio torch, não um `ValueError` do PatchCraft: `NotImplementedError` nas versões recentes e `RuntimeError`, a classe-base dele, no torch 2.6.
+  `extract` só copia: cada patch é uma janela com stride sobre a imagem, materializada por uma cópia, então os valores saem bit a bit iguais aos da imagem em qualquer dtype. Até 0.5.6 os inteiros passavam pelo `F.unfold`, que não tem kernel inteiro em CPU, e falhavam com o erro do próprio torch; a view com stride que o substituiu tem kernel para todo dtype. Medido em CPU; nenhum caminho inteiro executou em GPU.
 - `patch_size`, `stride`, `dilation` como `int` (quadrado) ou `(int, int)` com valores positivos.
 - Patch maior que imagem → retorna `Tensor[0, C, ph, pw]` (não levanta).
 - `stride > patch_size` (grid esparso com lacunas, válido para features que não fazem round-trip; ver §9.2 para a contrapartida em `reconstruct`).
@@ -286,7 +286,8 @@ Esta seção consolida, por API, as condições que v0.1 deve **aceitar**, **rej
 **Aceita:**
 - `sh ≤ ph` e `sw ≤ pw` (cobertura total ou overlap).
 - `image_shape` igual a `(C, H, W)` consistente com a geometria implícita pelo `patches.shape[0]`.
-- Dtypes float (`float16/float32/float64/bfloat16`). Dtypes inteiros **não** funcionam: `col2im_out_cpu` não é implementado para `Byte`/`Int`/`Long`, simetricamente ao `extract` em §9.1. Desde 0.2.1, `reconstruct` tem guarda de dtype e rejeita inteiros com `ValueError` claro (em 0.2.0 o erro era um `NotImplementedError` cru do torch).
+- Dtypes float (`float16/float32/float64/bfloat16`) e os cinco inteiros (`uint8`, `int8`, `int16`, `int32`, `int64`).
+- Sobre os inteiros: o resultado é, em cada pixel, a média exata dos valores que os patches dão a ele, arredondada para o par mais próximo, o mesmo arredondamento que `resize` aplica a inteiros (§9.4). Para patches vindos do `extract` todos os valores de um pixel são o mesmo `v`, a soma é `k·v` e o resultado é `v`: o round trip é exato **em toda geometria legal**, sem a regra do mapa de cobertura, que é uma regra de ponto flutuante. Nenhum intermediário estoura: até `int32` a soma é feita em `int64`, e em `int64` cada valor é dividido pela contagem do seu pixel antes da soma, em quociente e resto, de modo que a soma dos quocientes não passa do maior valor de entrada e a dos restos fica abaixo de `k²`. O acelerador nativo não tem caminho inteiro e deixa esses casos com o torch. Medido em CPU, contra a mesma média calculada em inteiros do Python (`tests/test_integer.py`).
 - Sobre `float16`: o `F.fold` acumula a soma de todos os patches sobrepostos *antes* de dividir pelo count map, e o numerador estoura o máximo finito de fp16 (65504) bem antes de a divisão acontecer. Medido em 0.2.0: imagem fp16 `(1, 16, 16)` constante de valor `10000.0`, `ph=pw=3`, `stride=1`, devolveu `inf` em **144 de 256** pixels. Desde 0.2.1 a acumulação interna (fold, count map, divisão) é feita em `float32`, com cast de volta ao dtype original no retorno; `stitch` faz o mesmo (§9.9).
 - Sobre `bfloat16`: é promovido do mesmo jeito, **mas não pela mesma razão**, e até 0.5.2 este documento dizia que sim. O `bfloat16` carrega o expoente do `float32`, então não estoura: no caso acima o numerador chegou a `9.0112e+04` contra um máximo finito de `3.390e+38`, sem nenhum `inf`. O que a promoção compra nele é exatidão, já que tem 8 bits de mantissa contra os 11 do `float16`: em 1×16×16, `ph = pw = 3`, `stride = 1`, com dado `torch.rand` gerado em `bfloat16`, acumular nativamente erra até `7.812e-03`, dois passos do `bfloat16` perto de 1, e promovendo o round trip devolve a entrada bit a bit, embora o mapa tenha contagens 3, 6 e 9: o arredondamento final para 8 bits absorve o erro do acumulador em `float32`. É o menos preciso dos dois formatos justamente por trocar mantissa por expoente.
 
@@ -296,6 +297,7 @@ Esta seção consolida, por API, as condições que v0.1 deve **aceitar**, **rej
 - Grade truncada: `(num_h - 1) * sh + ph != H` ou `(num_w - 1) * sw + pw != W` (o último patch tem que terminar exatamente na borda da imagem; grades truncadas zeravam pixels silenciosamente em 0.2.0, medido `10×10` patch 4 stride 4 → 36 de 100 zerados, `13×13` patch 5 stride 5 → 69 de 169; guarda adicionada em 0.2.1).
 - `image_shape` inconsistente com `patches.shape[0]` / `stride`.
 - `patches.ndim != 4`.
+- `bool` e complexos: a média de booleanos é uma votação, que o ADR 0004 reserva a uma função própria, e os complexos não têm regra de arredondamento aqui.
 
 **Fora de escopo v0.1:**
 - Output em PIL.

{patchcraft-0.5.6 → patchcraft-0.5.7}/docs/USAGE.md

@@ -233,9 +233,26 @@ value; sum is `k * value`; division by the count map gives back
 `stride == patch_size` always qualifies and `stride == patch_size / 2`
 does too (counts 1, 2, 4, as above). Otherwise the error is bounded
 per pixel by `(k+1)·eps·|v|`,
-whatever the dtype: the deciding axis is the geometry, not the
+whatever the float dtype: the deciding axis is the geometry, not the
 precision.
 
+Integer images have no such rule. Their sums do not round, so they come
+back exact in every legal geometry, here at patch 3 and stride 1, where
+counts reach 9:
+
+```python
+>>> as_int = img.to(torch.int16)   # the 28x28 image above, as integers
+>>> back = reconstruct(extract(as_int, patch_size=3, stride=1),
+...                    image_shape=as_int.shape, stride=1)
+>>> back.dtype, torch.equal(back, as_int)
+(torch.int16, True)
+
+```
+
+Patches that disagree get their exact mean rounded half to even, and
+`bool` patches are refused, since their mean is a vote
+([`THEORY.md`](THEORY.md) §9.2).
+
 When the patches disagree, which is what a model's output does, each pixel
 gets the mean of what its patches say. Below, nine overlapping patches cover
 the tiny image; the middle one says 1 and the other eight say 0:

{patchcraft-0.5.6 → patchcraft-0.5.7}/src/patchcraft/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.6'
-__version_tuple__ = version_tuple = (0, 5, 6)
+__version__ = version = '0.5.7'
+__version_tuple__ = version_tuple = (0, 5, 7)
 
-__commit_id__ = commit_id = 'gc0bd52ca3'
+__commit_id__ = commit_id = 'gd41e635eb'

{patchcraft-0.5.6 → patchcraft-0.5.7}/src/patchcraft/extract.py

@@ -1,4 +1,4 @@
-"""Patch extraction: strided-window fast path, F.unfold for dilation > 1.
+"""Patch extraction: a strided window view and one copy, for every dtype.
 
 Contract: docs/THEORY.md §1 and §9.1, docs/ADR/0001-patch-extraction-api.md,
 docs/ADR/0002-patchify-transform.md.
@@ -6,29 +6,10 @@ docs/ADR/0002-patchify-transform.md.
 from __future__ import annotations
 
 import torch
-import torch.nn.functional as F  # noqa: N812 (torch convention)
 
 __all__ = ["Patchify", "extract"]
 
 
-# Dtypes that F.unfold (im2col) supports on CPU in torch 2.x. The dilation == 1
-# fast path is restricted to these to keep the accept/reject contract unchanged:
-# Tensor.unfold views accept any dtype, but integer dtypes must still raise
-# from im2col (NotImplementedError, or RuntimeError on torch 2.6), so they fall
-# through to F.unfold as before.
-_FAST_PATH_DTYPES = frozenset(
-    {
-        torch.bool,
-        torch.float16,
-        torch.bfloat16,
-        torch.float32,
-        torch.float64,
-        torch.complex64,
-        torch.complex128,
-    }
-)
-
-
 def _as_pair(value: int | tuple[int, int], name: str) -> tuple[int, int]:
     if isinstance(value, int) and not isinstance(value, bool):
         if value <= 0:
@@ -57,7 +38,9 @@ def extract(
     Returns `Tensor[L, C, ph, pw]` in row-major order. Patch `k` has its
     top-left at `(k // num_w * sh, k % num_w * sw)`. Truncation is the only
     boundary policy: if the geometry fits no patch, returns `Tensor[0, C, ph, pw]`.
-    Dtype and device of `image` are preserved.
+    Dtype and device of `image` are preserved. Every dtype is accepted, the
+    integer ones and bool included, at every dilation: extraction only copies,
+    so each patch holds the image's own values bit for bit.
     """
     if not isinstance(image, torch.Tensor):
         raise TypeError(f"image must be torch.Tensor, got {type(image).__name__}")
@@ -75,32 +58,28 @@ def extract(
     if h < eff_h or w < eff_w:
         return torch.empty(0, c, ph, pw, dtype=image.dtype, device=image.device)
 
-    if dh == 1 and dw == 1 and image.dtype in _FAST_PATH_DTYPES:
-        # Fast path: strided window view + one copy. Measured 13-21x faster
-        # than F.unfold (im2col) on CPU, bit-exact (same pixels, same order).
-        nh = (h - ph) // sh + 1
-        nw = (w - pw) // sw + 1
-        windows = image.unfold(1, ph, sh).unfold(2, pw, sw)  # (C, nh, nw, ph, pw)
-        # Exactly one copy in every case. A reshape would copy too, except on
-        # degenerate geometries (e.g. ph == pw == 1), where the permuted window
-        # is already contiguous and reshape would return a view aliasing the
-        # image, which the contract forbids. Cloning unconditionally covers
-        # that case without asking the tensor for its storage, which a
-        # torch.vmap batched tensor does not have.
-        return (
-            windows.permute(1, 2, 0, 3, 4)
-            .clone(memory_format=torch.contiguous_format)
-            .view(nh * nw, c, ph, pw)
-        )
-
-    unfolded = F.unfold(
-        image.unsqueeze(0),
-        kernel_size=(ph, pw),
-        dilation=(dh, dw),
-        stride=(sh, sw),
+    # A strided window view and exactly one copy, for every dtype and dilation.
+    # The window spans the dilated footprint and the slice keeps every d-th
+    # pixel of it. Against F.unfold (im2col), which this replaced: the same
+    # values bit for bit, 13 to 21 times faster at dilation 1 and 3.9 times at
+    # dilation 2 on 3x1024x1024, and a kernel for every dtype where im2col has
+    # none for integers.
+    nh = (h - eff_h) // sh + 1
+    nw = (w - eff_w) // sw + 1
+    windows = image.unfold(1, eff_h, sh).unfold(2, eff_w, sw)  # (C, nh, nw, eh, ew)
+    if dh > 1 or dw > 1:
+        windows = windows[..., ::dh, ::dw]                      # (C, nh, nw, ph, pw)
+    # Exactly one copy in every case. A reshape would copy too, except on
+    # degenerate geometries (e.g. ph == pw == 1), where the permuted window
+    # is already contiguous and reshape would return a view aliasing the
+    # image, which the contract forbids. Cloning unconditionally covers
+    # that case without asking the tensor for its storage, which a
+    # torch.vmap batched tensor does not have.
+    return (
+        windows.permute(1, 2, 0, 3, 4)
+        .clone(memory_format=torch.contiguous_format)
+        .view(nh * nw, c, ph, pw)
     )
-    return unfolded[0].view(c, ph, pw, -1).permute(3, 0, 1, 2).contiguous()
-
 
 class Patchify:
     """Callable that extracts patches with a frozen geometry.