patchcraft 0.5.7__tar.gz → 0.6.0__tar.gz

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

@@ -6,6 +6,52 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-11
+
+A new `0.y` because `resize` gains a parameter, `antialias`, whose default
+changes no call. With it comes a faster `stitch` under the uniform window,
+bit-identical to the code it replaces. No returned value of an existing call
+changes. The full suite passes on both code paths at the declared floor and
+at the newest releases, and the 126,736-geometry sweep passes on both paths.
+
+### Changed
+
+- **`stitch` with the uniform window hands an overlapping grid to
+  `reconstruct`.** Every weight is 1, so the weighted fold is the plain fold
+  in the same order and the separable denominator is the count map, which is
+  `reconstruct`'s arithmetic without the multiply by ones and the two window
+  folds. Compared against the previous code through integer views: 996
+  geometries of the sampled space, four float dtypes, signed zeros,
+  infinities, NaN payloads and subnormals, outputs and gradients, both code
+  paths, 0 differences. Against the previous code, interleaved and taking the
+  median of 9 to 41 runs: 1.45 and 1.75 times faster on the pure path at
+  3x512x512 and 3x1024x1024 and 1.06 at 3x2048x2048, where the fold dominates,
+  and 1.31, 1.17 and 1.10 times with the accelerator. A non-overlapping grid
+  takes the same path as before. The test that compared the two with
+  `allclose` now compares bits, counts of 3 included.
+
+### Added
+
+- **`resize(..., antialias=None)`**, keyword-only, with the name, values and
+  meaning of torchvision v2's `resize` and the default ADR 0004 recorded. With
+  `True` the torch backend filters before a bilinear or bicubic downsample, as
+  PIL always does. On the tests' noise image reduced by 4 it lands within
+  1/255 of the PIL backend, where the unfiltered path is more than 20/255
+  away, and it passes a third of the noise's standard deviation. For float
+  tensors the output equals torchvision v2's `resize(antialias=True)` bit for
+  bit; half precision is filtered in `float32` and cast back, as torchvision
+  does, because torch has no antialiased half-precision kernel. Integer
+  tensors are rounded and clamped as on every other path, where torchvision
+  rounds `uint8` in its own fixed-point kernel, so the two can differ there.
+  `None` and `False` leave the call to `F.interpolate` exactly as it was, so
+  no existing call changes, and the flag is ignored where it means nothing,
+  the other torch modes and the PIL backend, as torchvision ignores it. The
+  filtered path uses PIL's bicubic kernel (`a = -0.5`) where the plain one
+  uses torch's (`a = -0.75`), so it changes bicubic enlargement too, and the
+  docs say it is for reducing. With the flag, resizing to the same size
+  returns the input bit for bit. Removing the flag from either call site, or
+  the half-precision promotion, fails the new tests.
+
 ## [0.5.7] - 2026-10-10
 
 Integer images, end to end. `extract` takes every dtype at every dilation,
@@ -1207,7 +1253,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.7...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.6.0
 [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

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

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

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

@@ -275,6 +275,11 @@ moved, or whether the implementation stopped violating it**:
 | Documentation, tests, CI, packaging or tooling only | `0.y.Z` | Still a release if it is published, still no break |
 | Nothing published | nothing | Accumulate under `[Unreleased]` |
 
+A new keyword-only parameter with a default breaks no call, but it moves a
+signature, so it takes the first row and not the third: 0.6.0 is the example,
+where `resize` gained `antialias`. The third row is for new behaviour behind
+an unchanged signature, such as 0.5.7 accepting integer images.
+
 The project's own history sorts cleanly under that rule, and does not sort
 under any rule keyed on whether values changed:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.7
+Version: 0.6.0
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT

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

@@ -6,12 +6,12 @@
 
 ## Where the project is
 
-**0.5.7 is on PyPI**, published through Trusted Publishing on a tag push: one
+**0.6.0 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.
 
-**1971 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
+**2024 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.7 brings integer images: `extract` takes every
+**Nothing unreleased.** 0.6.0 added `resize(..., antialias=None)`,
+keyword-only with the default that changes no call, and made `stitch` with
+the uniform window hand an overlapping grid to `reconstruct`, bit-identical and
+1.45 to 1.75 times faster on the pure path at 512 and 1024. The new parameter
+is why it is a new `0.y`, by the README's rule and the first row of
+CONTRIBUTING's table.
+
+0.5.7 brought 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.
@@ -63,10 +70,11 @@ power-of-two ones, and a `float64` accumulator on all 76. The three-letter
 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 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
+effort parameters as a design that is mostly not built; the status reflects
+that `accum_dtype`, `rounding_mode` and the preset are not implemented, not
+that a decision is pending. What it records that did ship: its steps 1 and 2,
+integers through `extract` and `reconstruct` without a knob, in 0.5.7, and its
+third parameter, `resize(..., antialias=None)`, in 0.6.0. 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.7 → patchcraft-0.6.0}/docs/ADR/0004-precision-and-effort-parameters.md

@@ -39,13 +39,15 @@ a keyword-only argument with a default is additive, so adding one after 1.0 cost
 release and nothing else. With the premise checked and gone, YAGNI, the absence of any
 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
+**So this ADR asks nothing.** It records a design that is mostly not built, the names precedent
 determines, the constraint that would make a preset safe, and the order. It stays `Proposed`
-because none of its parameters is implemented, not because a decision is pending.
+because two of its three parameters, `accum_dtype` and `rounding_mode`, and the preset are not
+implemented, not because a decision is pending.
 
-**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.
+**What is implemented is the integer path without a knob, and `antialias`:** 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, and `antialias` followed the same day, with the name, values and
+default of section 1. `accum_dtype` and `rounding_mode` do not exist.
 
 ## 1. The names, determined by precedent
 
@@ -178,8 +180,9 @@ into a `precise` tier would sell the absence of a bug as a quality level. **Step
 2026-09-03**, and the three were the `stitch` denominator floor, the `reconstruct`
 single-patch aliasing and the `resize` inbound clamp on a dtype that cannot hold the bound.
 The remaining items named in the audit, the `bfloat16` justification in THEORY 9.2 and the
-resize antialias gap, are still open and are not defects of the same kind: the first is a
-documentation correction and the second is a user-facing choice that needs its own release. Document, at zero
+resize antialias gap, were not defects of the same kind: the first was a documentation
+correction, closed in 0.5.6, and the second a user-facing choice, which `antialias=None` as the
+default made additive when it landed on 2026-10-10. Document, at zero
 cost, the rounding policy already in force. Freeze 1.0 at 20 names with no new parameters.
 Then 1.1 brings steps 1 and 2 together and unrestricted. Then stop and wait for a user:
 only if one appears do the knobs follow, and the preset last of all.

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

@@ -668,7 +668,7 @@ The reason is visible in the uniform column, which does not move at all. Uniform
 ### The three windows, and what each costs
 
 - **`"uniform"`** is the default. Every covering patch contributes equally, which is exactly `reconstruct`'s arithmetic, and it puts the whole disagreement on the grid lines.
-- **`"hann"`** is the strong seam suppressor. On an overlapping grid the three windows cost the same, since the fold dominates, and only uniform skips the fold where `stride == patch_size`. It is the interior of a longer symmetric Hann window, `hann_window(n + 2, periodic=False)[1:-1]`, so it is strictly positive on every sample and never zeroes a pixel. A plain symmetric window is exactly zero at both endpoints and would zero every pixel covered only by patch edges; [THEORY.md](THEORY.md) §2.5 measures it.
+- **`"hann"`** is the strong seam suppressor. On an overlapping grid hann and gaussian cost the same, since the fold dominates, while uniform costs what `reconstruct` costs, because it is `reconstruct`'s arithmetic; where `stride == patch_size` uniform skips the fold altogether. It is the interior of a longer symmetric Hann window, `hann_window(n + 2, periodic=False)[1:-1]`, so it is strictly positive on every sample and never zeroes a pixel. A plain symmetric window is exactly zero at both endpoints and would zero every pixel covered only by patch edges; [THEORY.md](THEORY.md) §2.5 measures it.
 - **`"gaussian"`** keeps far more weight at the patch edge than hann does, so it suppresses seams less at the larger patch sizes in the sweep, and it wins at the smallest one. THEORY §2.5 states the tradeoff as weaker seam suppression than Hann in exchange for a flatter window.
 
 **Hann costs fidelity, and the cost is already in the numbers above.** Measured against the model's own patches, uniform keeps 29.60 dB mean and hann keeps 27.15 dB. Hann is trading exactness for smoothness on purpose, so if what you want back is the model's output rather than a pleasant image, uniform is the honest choice.
@@ -914,7 +914,7 @@ The table below is the one place that records what each call allocates, which is
 | `extract` | `image`, `patch_size`, `stride`, `dilation` | `(L, C, ph, pw)` | the whole patch stack, `L * C * ph * pw` values |
 | `Patchify` | the same geometry, at construction | a callable returning `(L, C, ph, pw)` | nothing beyond the geometry, no cache and no buffer |
 | `reconstruct` | `patches`, `image_shape`, `stride`, `dilation` | `(C, H, W)` | one image plus one count map |
-| `stitch` | the same, plus keyword-only `weight=`, default `"uniform"` | `(C, H, W)` | one image, one weight map, one `(ph, pw)` kernel, and on the pure-torch path a full weighted copy of the patch stack, which is the largest of the four and which the accelerated path skips |
+| `stitch` | the same, plus keyword-only `weight=`, default `"uniform"` | `(C, H, W)` | under `"uniform"`, what `reconstruct` allocates; under `"hann"` and `"gaussian"`, one image, one weight map, one `(ph, pw)` kernel, and on the pure-torch path a full weighted copy of the patch stack, which is the largest of these and which the accelerated path skips |
 | `WeightKind` | nothing, it is a `Literal` type alias | `"uniform"`, `"hann"` or `"gaussian"` today; the set is **open**, so a new member may arrive in a `0.y` / minor release and an exhaustive `match` on it should carry a fallback | nothing |
 | `pair` | `lr_image`, `hr_image`, `lr_patch_size`, `scale_factor`, `stride` | `PatchPair` | both patch stacks plus `L` metadata records |
 | `PatchPair`, `PatchMeta` | frozen dataclasses | patches and grid coordinates | metadata stays on CPU, always |
@@ -924,7 +924,7 @@ The table below is the one place that records what each call allocates, which is
 | `paired_tilings` | LR and HR shapes | `list[PairedTilingSpec]` | one spec per legal pair, no pixels |
 | `patch_metrics` | two same-shape tensors | `{mae, mse, max_abs, psnr_db}` | accumulates in float64, returns Python floats |
 | `per_patch_mse`, `per_patch_psnr` | two `(L, C, h, w)` stacks | `(L,)` in float64 | one value per patch |
-| `resize` | one tensor or `PIL.Image`, `target_size`, `backend` | the type it received | one resized image |
+| `resize` | one tensor or `PIL.Image`, `target_size`, `backend`, `antialias` | the type it received | one resized image |
 | `Cache` | `root`, `namespace`, `version` | a content-addressed store | files on disk, zstd payloads when installed |
 | `accel_available` | nothing | `bool`, true when this install has the native extension | nothing beyond a cached import probe on first call |
 
@@ -963,9 +963,9 @@ The LR and HR pairing symbols, which are `pair`, `paired_tilings` and `scale_fac
 
 ## 8. Where this applies today
 
-**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.
+**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, so pin the `0.y` you tested against with `~=0.y.0` to take its fixes only.
 
-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`.
+What is verified is this. The full local run of `pytest -m "not gpu"` passes 2024 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.
 
@@ -1018,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.7},   % check CHANGELOG.md for the release you used
+  version = {0.6.0},   % check CHANGELOG.md for the release you used
   year    = {2026},
   url     = {https://github.com/LeoPR/PatchCraft}
 }

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

@@ -133,7 +133,7 @@ For *unmodified* patches, every `patch_k(i_k, j_k)` equals `img(x, y)` (definiti
 
 **Window kernels.**
 
-- **`uniform`**: `w ≡ 1`. Numerator becomes the same as `reconstruct`'s fold; denominator becomes the count map. Mathematically equivalent to `reconstruct`. Provided so the API is one function with a parameter instead of two functions with a hidden choice.
+- **`uniform`**: `w ≡ 1`. Numerator becomes the same as `reconstruct`'s fold; denominator becomes the count map. On an overlapping grid `stitch` hands the call to `reconstruct`, so the two agree bit for bit. On a non-overlapping one `reconstruct` only copies, while `stitch` returns what the fold would: `+0.0` for a `-0.0`, and a NaN that stays a NaN but may change its bits. Provided so the API is one function with a parameter instead of two functions with a hidden choice.
 - **`hann`**: separable Hann (`outer(hann(ph), hann(pw))`). Center weight is 1, edge weight is small. Strong seam suppression.
 
   The 1-D window is the **interior of a longer symmetric Hann window**: `hann_window(n + 2, periodic=False)[1:-1]`, which is strictly positive on every sample, instead of the plain symmetric window `0.5·(1 − cos(2πi/(n−1)))`, which is exactly zero at both endpoints. The zero-endpoint variant was the single largest defect found by the 0.2.0 audit (measured 2026-08-03, fixed in 0.2.1): every pixel whose only covering patches placed it on a patch edge had numerator and denominator both ≈ 0, and the `clamp(min=1e-6)` divisor sent it to zero. Measured on the defective version: at `12×12, ph=pw=4, stride=4`, **108 of 144 pixels** came back zero; at `13×13, ph=pw=4, stride=3`, **105 of 169**, including black bands in the image interior; `patch_size=2` degenerated to an all-zero window and returned an all-black image with no error.
@@ -228,7 +228,7 @@ LR and HR must agree on dtype and device; mismatch is rejected (caller normalize
 - **PIL**: canonical dataset generation (reproducibility is paramount, result stays on CPU anyway).
 - **torch**: in-training augmentation where the tensor is already on GPU and the extra filter divergence does not matter.
 
-**Design decision.** One function: `patchcraft.resize(image, target_size, backend="pil", resample=None)`. `target_size` is a `(H, W)` tuple, with no size-spec DSL. `image` may be `PIL.Image` or `Tensor[C, H, W]`. Output type matches input (PIL in → PIL out, Tensor in → Tensor out), regardless of backend. `resample` defaults: `LANCZOS` for PIL, `bilinear` for torch (chosen because bicubic divergence is nastiest to debug; bilinear's difference from PIL's BILINEAR is small). Cross-backend conversions (PIL ↔ Tensor) go through a normalized float32 `[0, 1]` intermediate. No auto-selection: callers pick the backend explicitly and own the consequences.
+**Design decision.** One function: `patchcraft.resize(image, target_size, backend="pil", resample=None, *, antialias=None)`. `target_size` is a `(H, W)` tuple, with no size-spec DSL. `image` may be `PIL.Image` or `Tensor[C, H, W]`. Output type matches input (PIL in → PIL out, Tensor in → Tensor out), regardless of backend. `resample` defaults: `LANCZOS` for PIL, `bilinear` for torch (chosen because bicubic divergence is nastiest to debug; bilinear's difference from PIL's BILINEAR is small). Cross-backend conversions (PIL ↔ Tensor) go through a normalized float32 `[0, 1]` intermediate. No auto-selection: callers pick the backend explicitly and own the consequences.
 
 ## 6. Quantization (optional)
 
@@ -331,7 +331,7 @@ Retorna `PatchPair(lr_patches, hr_patches, metas)` (frozen dataclass com `__slot
 - `dilation` customizado (fixo em 1, porque o round-trip exige).
 - Coerção implícita LR→HR de dtype/device (caller normaliza antes).
 
-### 9.4 `resize(image, target_size, backend="pil", resample=None)`
+### 9.4 `resize(image, target_size, backend="pil", resample=None, *, antialias=None)`
 
 **Aceita:**
 - `image` é `PIL.Image` em qualquer mode suportado pelo PIL.
@@ -339,6 +339,7 @@ Retorna `PatchPair(lr_patches, hr_patches, metas)` (frozen dataclass com `__slot
 - `image` é `Tensor` em CUDA **apenas se** `backend == "torch"`.
 - `target_size = (H, W)` tupla de 2 ints positivos.
 - `resample=None` → default por backend (LANCZOS pra PIL, bilinear pra torch).
+- `antialias`: `None` (default), `False` ou `True`, com o nome e o sentido do `resize` do torchvision v2 (ADR 0004). Com `True`, o backend torch filtra antes de reduzir em `bilinear` e `bicubic`, como o PIL sempre faz: na imagem de ruído dos testes, reduzida 4×, o resultado fica a menos de 1/255 do backend PIL, contra mais de 20/255 sem o filtro (`tests/test_resize.py`). Meia precisão é filtrada em `float32` e convertida de volta, como no torchvision, porque o torch não tem kernel com antialias para ela. `None` e `False` deixam a chamada ao `F.interpolate` exatamente como era, então a saída padrão não muda. Nos outros modos do torch e no backend PIL o flag não tem sentido e é ignorado, como no torchvision. O caminho filtrado usa o bicúbico do PIL (`a = -0,5`) onde o comum usa o do torch (`a = -0,75`), então também muda a ampliação bicúbica; serve para reduzir.
 - Tensor inteiro com `backend == "torch"`: interpolação em float, cast de volta com **round + clamp** ao range do dtype (bicubic ultrapassa o range de entrada legitimamente, e um cast cru wrapava: `-9.0 → 247` em uint8; corrigido em 0.2.1). Vale para **todos os cinco modos** aceitos, não só para os dois que ultrapassam: o `F.interpolate` não implementa nenhum deles para inteiro, e até 0.5.3 a promoção era condicionada a `bilinear`/`bicubic`, então 13 das 25 combinações modo × dtype levantavam um erro cru do torch (`"adaptive_avg_pool2d" not implemented for 'Int'`) contra o que esta cláusula promete. A promoção é para o **float mais estreito que representa a faixa inteira do dtype exatamente**: `float32` para `uint8`, `int8` e `int16`, cujas faixas cabem nos 24 bits de mantissa, e `float64` para `int32`, que não cabe (`2**24 + 1` voltava `2**24`, em silêncio, desde sempre no caminho bilinear). `int64` é a exceção que nenhum float cobre: acima de `2**53` o valor não é exatamente representável em lugar nenhum e não sobrevive à volta.
 - Tensor float com `backend == "pil"`: o hop uint8 pelo PIL **clampa a `[0, 1]`**; valores fora desse intervalo não sobrevivem nesse backend (comportamento documentado, não exceção).
 - Tensor inteiro com `backend == "pil"`: o mesmo hop uint8 **clampa a `[0, 255]`** na ida e satura ao range do dtype na volta. Os dois backends recusam-se a dar a volta (`wrap`), que é a classe de defeito da 0.2.0, mas saturam em ranges diferentes de propósito: o torch preserva 300 e −9 num int32, o PIL não. Até 0.5.1 a ida fazia `clamp(0, 255)` no dtype de entrada, e num `int8` o próprio limite era irrepresentável, então o torch levantava `RuntimeError` cru antes de limitar coisa alguma.
@@ -348,6 +349,7 @@ Retorna `PatchPair(lr_patches, hr_patches, metas)` (frozen dataclass com `__slot
 - `target_size` não é 2-tupla ou contém valor ≤ 0.
 - `backend` não em `{"pil", "torch"}`.
 - `resample` não suportado pelo backend escolhido (mensagem amigável, não trace interno).
+- `antialias` que não seja `bool` nem `None`.
 
 **Fora de escopo v0.1:**
 - Auto-seleção de backend.
@@ -459,7 +461,7 @@ The blending counterpart to `reconstruct`. Same fold geometry, same rejections;
 - `patches` is a 4-D `(L, C, ph, pw)` floating-point tensor (`float16`, `bfloat16`, `float32`, `float64`).
 - `image_shape == (C, H, W)` consistent with the patch grid implied by `patches.shape[0]`, `stride`, and `(ph, pw)`.
 - `stride` as `int` or `(int, int)` with `1 ≤ stride ≤ patch_size` on every axis.
-- `weight` ∈ `{"uniform", "hann", "gaussian"}`. `"uniform"` is mathematically equivalent to `reconstruct`.
+- `weight` ∈ `{"uniform", "hann", "gaussian"}`. `"uniform"` returns what `reconstruct` returns, bit for bit on an overlapping grid, and on a non-overlapping one up to the sign of a zero and the bits of a NaN (§2.5).
 - `dtype` and `device` preserved on output.
 
 **Sinaliza (não exceção):**

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

@@ -449,8 +449,23 @@ tensor([[ 2.5000,  2.5000,  4.5000,  4.5000],
 
 The round trip does not return `tiny`: a resize discards what it averages,
 which is why ADR 0003 counts it among the inexact operations. The averaging
-holds at a factor of 2; at larger factors the torch backend samples rather
-than averages, because it does not antialias, while the PIL backend does.
+holds at a factor of 2. At larger factors the torch backend samples rather
+than averages unless you pass `antialias=True`, which filters first, as the
+PIL backend always does. A strip with two bright pixels, reduced by 4:
+
+```python
+>>> spikes = torch.tensor([[[0., 0., 0., 8., 0., 0., 0., 8.]]])
+>>> resize(spikes, target_size=(1, 2), backend="torch")[0]
+tensor([[0., 0.]])
+>>> resize(spikes, target_size=(1, 2), backend="torch", antialias=True)[0]
+tensor([[1.4286, 2.2857]])
+
+```
+
+Unfiltered, each output interpolates the two inputs nearest to it, and both
+pairs are zeros, so the bright pixels vanish. Filtered, every input under an
+output counts, so they are averaged in. The default stays unfiltered, so an
+existing call returns what it always did.
 
 PIL in → PIL out. Tensor in → Tensor out. Cross-backend
 (tensor + `backend="pil"`, or PIL + `backend="torch"`) is supported

{patchcraft-0.5.7 → patchcraft-0.6.0}/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.7'
-__version_tuple__ = version_tuple = (0, 5, 7)
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
-__commit_id__ = commit_id = 'gd41e635eb'
+__commit_id__ = commit_id = 'g737570549'

{patchcraft-0.5.7 → patchcraft-0.6.0}/src/patchcraft/resize.py

@@ -127,6 +127,7 @@ def _resize_torch(
     tensor: torch.Tensor,
     target_size: tuple[int, int],
     resample: str | None,
+    antialias: bool | None = None,
 ) -> torch.Tensor:
     if resample is None:
         mode = "bilinear"
@@ -151,6 +152,17 @@ def _resize_torch(
     kwargs: dict[str, Any] = {"size": target_size, "mode": mode}
     if mode in {"bilinear", "bicubic"}:
         kwargs["align_corners"] = False
+        # Only True reaches F.interpolate, and only for the two modes it
+        # implements antialiasing for; elsewhere the flag means nothing and is
+        # ignored, as torchvision's resize ignores it. None and False leave the
+        # call exactly as it was, so the default output is unchanged.
+        if antialias:
+            kwargs["antialias"] = True
+            # torch implements the antialiased kernels for float32 and float64
+            # only, and raises on half precision; filter it in float32 and cast
+            # back, as torchvision's resize does.
+            if x.dtype in (torch.float16, torch.bfloat16):
+                x = x.float()
     out = F.interpolate(x, **kwargs)
     if not original_dtype.is_floating_point:
         # Integer dtypes: bicubic/bilinear overshoot the input range, and a
@@ -166,6 +178,8 @@ def resize(
     target_size: tuple[int, int],
     backend: Literal["pil", "torch"] = "pil",
     resample: str | None = None,
+    *,
+    antialias: bool | None = None,
 ) -> torch.Tensor | PILImage:
     """Resize a single image, preserving input type.
 
@@ -179,6 +193,19 @@ def resize(
     bilinear for ``"torch"``. The accepted resample strings differ between
     backends; an unsupported choice raises ``ValueError``.
 
+    ``antialias=True`` makes the ``"torch"`` backend low-pass filter before
+    it downsamples, for ``bilinear`` and ``bicubic``, which is what PIL always
+    does; without it each output pixel interpolates only its nearest inputs
+    and the rest are skipped, so fine detail aliases. The filtered path is
+    torch's antialiased kernel, which also uses PIL's bicubic (``a = -0.5``)
+    where the plain path uses torch's (``a = -0.75``), so it changes bicubic
+    enlargement too; it is meant for reducing. Half precision is filtered in
+    ``float32`` and cast back. The flag means nothing for the other torch
+    modes and for the ``"pil"`` backend, and is ignored there, as in
+    torchvision's resize, whose name and meaning it borrows. ``None``, the
+    default, and ``False`` keep the torch backend unfiltered, exactly as
+    before the flag existed (ADR 0004).
+
     Dtype notes. Integer tensors on the ``"torch"`` backend are interpolated
     in float and cast back with round + clamp to the dtype range, because
     bicubic legitimately overshoots the input range and a bare cast wraps
@@ -195,9 +222,14 @@ def resize(
     Rejects (per §9.4): non-2-tuple or non-positive ``target_size``;
     ``backend`` not in ``{"pil", "torch"}``; CUDA tensor with
     ``backend="pil"``; unsupported ``resample`` for the chosen backend;
-    PIL tensor conversion of an unsupported channel count.
+    PIL tensor conversion of an unsupported channel count; ``antialias`` that
+    is neither a ``bool`` nor ``None``.
     """
     target_size = _validate_target_size(target_size)
+    if antialias is not None and not isinstance(antialias, bool):
+        raise ValueError(
+            f"antialias must be bool or None, got {type(antialias).__name__} {antialias!r}"
+        )
     if backend not in {"pil", "torch"}:
         raise ValueError(f"backend must be 'pil' or 'torch', got {backend!r}")
 
@@ -225,7 +257,7 @@ def resize(
                 info = torch.iinfo(original_dtype)
                 tensor_out = (tensor_out * 255).round().clamp(info.min, info.max)
             return tensor_out.to(original_dtype)
-        return _resize_torch(image, target_size, resample)
+        return _resize_torch(image, target_size, resample, antialias)
 
     # PIL branch.
     try:
@@ -240,5 +272,5 @@ def resize(
         return _resize_pil(image, target_size, resample)
     # PIL + backend == "torch"
     tensor = _pil_to_tensor_f32(image)
-    resized = _resize_torch(tensor, target_size, resample)
+    resized = _resize_torch(tensor, target_size, resample, antialias)
     return _tensor_to_pil_u8(resized)

{patchcraft-0.5.7 → patchcraft-0.6.0}/src/patchcraft/stitch.py

@@ -8,8 +8,11 @@ denoised, super-resolved, or otherwise altered, where overlap seams are
 visible if patches are averaged uniformly. Weighting by a window kernel
 (Hann, Gaussian) emphasizes patch centers and reduces those seams.
 
-With ``weight="uniform"``, ``stitch`` is mathematically equivalent to
-``reconstruct`` (down to floating-point ordering).
+With ``weight="uniform"``, ``stitch`` returns what ``reconstruct`` returns:
+on an overlapping grid it is the same computation, bit for bit. On a
+non-overlapping one ``reconstruct`` only copies, while ``stitch`` returns what
+the fold it stands in for would: ``+0.0`` for a ``-0.0``, and a NaN that stays
+a NaN but may change its bits.
 
 Contract: docs/THEORY.md §2.5 and §9.9.
 """
@@ -22,6 +25,7 @@ import torch.nn.functional as F  # noqa: N812 (torch convention)
 
 from patchcraft._accel import fold_weighted
 from patchcraft._foldgeom import check_fold_geometry
+from patchcraft.reconstruct import reconstruct
 
 __all__ = ["WeightKind", "stitch"]
 
@@ -153,7 +157,10 @@ def stitch(
     built from two 1-D window folds (the kernel is separable, so the 2-D
     denominator is their outer product). ``numerator / denominator`` gives
     the output; geometry validation guarantees no uncovered pixels and all
-    three windows are strictly positive.
+    three windows are strictly positive. Under ``"uniform"`` every weight is
+    1, so an overlapping grid goes to :func:`patchcraft.reconstruct`, which is
+    the same arithmetic without the multiply and the window folds, and a
+    non-overlapping grid is only rearranged.
 
     Rejects (per §9.9): ``dilation != 1``; ``stride > patch_size`` in any
     axis; grids that do not cover the image exactly (same coverage guard as
@@ -214,6 +221,16 @@ def stitch(
         out = grid.permute(2, 0, 3, 1, 4).reshape(c, h, w)
         return (out + 0.0).to(patches.dtype)
 
+    if weight == "uniform":
+        # Overlapping grid under the uniform window. Every weight is 1, so the
+        # weighted fold is the plain fold, in the same order, and the
+        # separable denominator is the count map: exactly the arithmetic
+        # reconstruct performs, without the multiply by ones and the two
+        # window folds. Bit-identical to the general path below, values,
+        # signed zeros, NaN payloads and gradients included; the speedup is
+        # measured in the 0.6.0 entry of CHANGELOG.md.
+        return reconstruct(patches, image_shape, stride)
+
     wh = _window_1d(weight, ph, accum_dtype, patches.device)
     ww = _window_1d(weight, pw, accum_dtype, patches.device)
     kernel = wh.unsqueeze(1) * ww.unsqueeze(0)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.7
+Version: 0.6.0
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT

patchcraft-0.6.0/src/patchcraft.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.6.0",
+  "distance": 0,
+  "node": "g737570549ab5e7b365503e0e05871742799caf83",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-11"
+}

{patchcraft-0.5.7 → patchcraft-0.6.0}/tests/test_public_api.py

@@ -106,6 +106,7 @@ class TestSignatures:
             ("target_size", POK, False, None),
             ("backend", POK, True, "pil"),
             ("resample", POK, True, None),
+            ("antialias", KO, True, None),
         ]
         assert _returns(patchcraft.resize) == "torch.Tensor | PILImage"
 

{patchcraft-0.5.7 → patchcraft-0.6.0}/tests/test_resize.py

@@ -7,6 +7,7 @@ import torch
 from PIL import Image
 
 from patchcraft import resize
+from tests._rng import bit_equal
 
 
 def _rgb_pil(h: int, w: int) -> Image.Image:
@@ -243,6 +244,134 @@ class TestBackendDivergence:
         assert out_torch.shape == out_pil.shape == (1, 8, 8)
 
 
+class TestAntialias:
+    """``antialias`` (ADR 0004): torchvision v2's flag, acting on the torch backend.
+
+    The default leaves the call as it always was; ``True`` filters before a
+    bilinear or bicubic downsample, which is what PIL always does."""
+
+    @staticmethod
+    def _noise() -> torch.Tensor:
+        return torch.rand(3, 256, 256, generator=torch.Generator().manual_seed(0))
+
+    def test_default_and_false_leave_the_call_unchanged(self) -> None:
+        x = self._noise()
+        default = resize(x, (64, 64), backend="torch")
+        plain = torch.nn.functional.interpolate(
+            x.unsqueeze(0), size=(64, 64), mode="bilinear", align_corners=False
+        )[0]
+        assert torch.equal(default, plain)
+        assert torch.equal(resize(x, (64, 64), backend="torch", antialias=False), default)
+
+    @pytest.mark.parametrize(
+        "dtype", [torch.float32, torch.float64, torch.float16, torch.bfloat16]
+    )
+    @pytest.mark.parametrize("mode", ["bilinear", "bicubic"])
+    def test_true_equals_torchvision_resize_for_float_tensors(
+        self, mode: str, dtype: torch.dtype
+    ) -> None:
+        """Float tensors only: for integers torchvision rounds differently (uint8
+        has a native fixed-point kernel), and resize rounds and clamps."""
+        tv = pytest.importorskip("torchvision.transforms.v2.functional")
+        x = self._noise().to(dtype)
+        ours = resize(x, (64, 64), backend="torch", resample=mode, antialias=True)
+        interpolation = getattr(tv.InterpolationMode, mode.upper())
+        theirs = tv.resize(x, [64, 64], interpolation=interpolation, antialias=True)
+        assert ours.dtype == dtype
+        assert bit_equal(ours, theirs)
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    @pytest.mark.parametrize("mode", ["bilinear", "bicubic"])
+    def test_half_precision_is_filtered_in_float32(self, mode: str, dtype: torch.dtype) -> None:
+        """torch has no antialiased half-precision kernel and raised on it."""
+        x = self._noise().to(dtype)
+        got = resize(x, (64, 64), backend="torch", resample=mode, antialias=True)
+        via = resize(x.float(), (64, 64), backend="torch", resample=mode, antialias=True)
+        assert bit_equal(got, via.to(dtype))
+        assert bit_equal(resize(x, (256, 256), backend="torch", antialias=True), x)
+
+    def test_a_pil_image_on_the_torch_backend_takes_the_flag(self) -> None:
+        from patchcraft.resize import _pil_to_tensor_f32, _tensor_to_pil_u8
+
+        stripes = Image.fromarray((np.indices((64, 64)).sum(0) % 2 * 255).astype(np.uint8))
+        filtered = resize(stripes, (16, 16), backend="torch", antialias=True)
+        plain = resize(stripes, (16, 16), backend="torch")
+        assert not np.array_equal(np.asarray(filtered), np.asarray(plain))
+        via = _tensor_to_pil_u8(
+            resize(_pil_to_tensor_f32(stripes), (16, 16), backend="torch", antialias=True)
+        )
+        assert np.array_equal(np.asarray(filtered), np.asarray(via))
+
+    @pytest.mark.parametrize(("flag", "a"), [(False, -0.75), (True, -0.5)])
+    def test_the_filtered_bicubic_is_pils_kernel(self, flag: bool, a: float) -> None:
+        """Enlarging an impulse traces the kernel: torch's Keys a = -0.75
+        without the flag, PIL's a = -0.5 with it, which is why the flag also
+        changes bicubic enlargement."""
+
+        def keys(t: float) -> float:
+            t = abs(t)
+            if t <= 1:
+                return (a + 2) * t**3 - (a + 3) * t**2 + 1
+            return a * t**3 - 5 * a * t**2 + 8 * a * t - 4 * a if t < 2 else 0.0
+
+        impulse = torch.zeros(1, 1, 16, dtype=torch.float64)
+        impulse[..., 8] = 1.0
+        up = resize(impulse, (1, 64), backend="torch", resample="bicubic", antialias=flag)[0, 0]
+        offsets = [(j + 0.5) / 4 - 0.5 - 8 for j in range(64)]
+        kernel = torch.tensor([keys(t) for t in offsets], dtype=torch.float64)
+        torch.testing.assert_close(up, kernel, rtol=0, atol=1e-12)
+
+    @pytest.mark.parametrize("mode", ["bilinear", "bicubic"])
+    def test_true_agrees_with_pil_when_downsampling(self, mode: str) -> None:
+        """Within the PIL backend's own uint8 rounding; the plain path does not come close."""
+        x = (self._noise()[:, :64, :64] * 255).round() / 255
+        pil = resize(x, (16, 16), backend="pil", resample=mode)
+        filtered = resize(x, (16, 16), backend="torch", resample=mode, antialias=True)
+        plain = resize(x, (16, 16), backend="torch", resample=mode)
+        assert (filtered - pil).abs().max() <= 1.0 / 255 + 1e-6
+        assert (plain - pil).abs().max() > 20.0 / 255
+
+    def test_noise_is_averaged_rather_than_sampled(self) -> None:
+        x = self._noise()
+        plain = resize(x, (64, 64), backend="torch")
+        filtered = resize(x, (64, 64), backend="torch", antialias=True)
+        assert filtered.std() < 0.4 * plain.std()
+
+    @pytest.mark.parametrize("mode", ["bilinear", "bicubic"])
+    def test_resizing_to_the_same_size_returns_the_input(self, mode: str) -> None:
+        """The round trip a resize has: to the size it already is, bit for bit."""
+        x = self._noise()
+        same = resize(x, (256, 256), backend="torch", resample=mode, antialias=True)
+        assert torch.equal(same, x)
+
+    @pytest.mark.parametrize("mode", ["nearest", "area", "nearest-exact"])
+    def test_ignored_by_the_modes_without_antialiasing(self, mode: str) -> None:
+        x = self._noise()
+        with_flag = resize(x, (64, 64), backend="torch", resample=mode, antialias=True)
+        assert torch.equal(with_flag, resize(x, (64, 64), backend="torch", resample=mode))
+
+    @pytest.mark.parametrize("flag", [True, False])
+    def test_ignored_by_the_pil_backend(self, flag: bool) -> None:
+        x = self._noise()
+        with_flag = resize(x, (64, 64), backend="pil", antialias=flag)
+        assert torch.equal(with_flag, resize(x, (64, 64), backend="pil"))
+
+    def test_integer_tensors_round_and_clamp_the_filtered_result(self) -> None:
+        u8 = (self._noise() * 255).round().to(torch.uint8)
+        got = resize(u8, (64, 64), backend="torch", antialias=True)
+        ref = torch.nn.functional.interpolate(
+            u8.unsqueeze(0).float(), size=(64, 64), mode="bilinear",
+            align_corners=False, antialias=True,
+        )[0].round().clamp(0, 255).to(torch.uint8)
+        assert got.dtype == torch.uint8
+        assert torch.equal(got, ref)
+
+    @pytest.mark.parametrize("bad", [1, 0, "yes"])
+    def test_rejects_anything_but_bool_or_none(self, bad: object) -> None:
+        with pytest.raises(ValueError, match="antialias must be bool or None"):
+            resize(self._noise(), (64, 64), backend="torch", antialias=bad)  # type: ignore[arg-type]
+
+
 # ------------------------------------------------------------------ Rejeita ---
 
 class TestRejects:

{patchcraft-0.5.7 → patchcraft-0.6.0}/tests/test_stitch.py

@@ -47,19 +47,39 @@ class TestUniformEqualsReconstruct:
         out = stitch(patches, image_shape=img.shape, stride=4, weight="uniform")
         assert bit_equal(out, img)
 
-    def test_overlap_matches_reconstruct(self) -> None:
-        """Equivalence is down to floating-point ordering by contract, so
-        this stays `allclose`, but on real noise rather than an integer ramp."""
-        img = rand_image(1, 16, 16, torch.float64, seed=503)
-        patches = extract(img, patch_size=4, stride=2)
-        out_stitch = stitch(patches, image_shape=img.shape, stride=2)
-        out_recon = reconstruct(patches, image_shape=img.shape, stride=2)
-        assert torch.allclose(out_stitch, out_recon, rtol=1e-12, atol=1e-12)
+    @pytest.mark.parametrize("accel", ["1", "0"], ids=["accel", "pure"])
+    @pytest.mark.parametrize(
+        "dtype", [torch.float32, torch.float64, torch.float16, torch.bfloat16]
+    )
+    @pytest.mark.parametrize(
+        ("h", "w", "p", "s"), [(16, 16, 4, 2), (12, 10, (4, 3), (2, 1)), (9, 7, 3, (1, 2))]
+    )
+    def test_overlap_is_reconstruct_bit_for_bit(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        accel: str,
+        dtype: torch.dtype,
+        h: int,
+        w: int,
+        p: int | tuple[int, int],
+        s: int | tuple[int, int],
+    ) -> None:
+        """On an overlapping grid the uniform window delegates to reconstruct,
+        so the two agree bit for bit, counts of 3 included, on patches that
+        disagree and on signed zeros, infinities and NaN payloads."""
+        monkeypatch.setenv("PATCHCRAFT_ACCEL", accel)
+        n, _, ph, pw = extract(torch.zeros(1, h, w), p, s).shape
+        g = torch.Generator().manual_seed(503)
+        patches = (torch.rand(n, 2, ph, pw, generator=g) * 2 - 1).to(dtype)
+        flat = patches.view(-1)
+        flat[:5] = torch.tensor([0.0, -0.0, float("inf"), float("-inf"), float("nan")])
+        out_stitch = stitch(patches, image_shape=(2, h, w), stride=s)
+        out_recon = reconstruct(patches, image_shape=(2, h, w), stride=s)
+        assert bit_equal(out_stitch, out_recon)
 
     def test_overlap_recovers_image(self) -> None:
         """counts are 1, 2, 4 (powers of two): uniform stitch is bit-exact
-        here, because the ones-kernel multiply is exact and the cumsum denominator
-        reproduces the integer count map exactly."""
+        here, since it is reconstruct's arithmetic on an overlapping grid."""
         img = rand_image(1, 16, 16, torch.float64, seed=504)
         patches = extract(img, patch_size=4, stride=2)
         out = stitch(patches, image_shape=img.shape, stride=2)

patchcraft-0.5.7/src/patchcraft.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.5.7",
-  "distance": 0,
-  "node": "gd41e635eb1e69e0c127c5cd4dde39fd8c76dc3a5",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-10"
-}