Seamless textures are a topology problem: diffusion, toroidal LoRAs, verification, and a production texture bank

A texture tile has one unforgiving property: the right edge is not really an edge. It is immediately followed by the left edge. The bottom is followed by the top. An image can look excellent in isolation and still fail instantly when repeated across a wall, terrain mesh, fabric, game level, or material sphere.

We built app.nz/textures around that distinction. The system does not publish an image because its prompt contained “seamless.” It generates a 2×2 proof, measures both wrap boundaries, repairs conservative failures, and only indexes tiles that pass the gate. Local diffusion runs at background priority, so building the library cannot jump ahead of interactive production traffic.

This article separates three things that are often blurred together:

1. what periodicity mathematically requires;
2. what current diffusion research has demonstrated;
3. what we implemented, what remains experimental, and how we will train the

next Z-Image LoRA without teaching it our own mistakes.

The topology is a torus, not a rectangle

A normal image lives on a bounded rectangle. A repeatable texture lives on a torus: moving past x = width returns to x = 0, and moving past y = height returns to y = 0. That changes how we should augment, score, embed, and generate it.

The discrete condition is slightly subtler than “the first and last pixels must be identical.” If a periodic sine wave is sampled at N positions, sample N-1 and sample 0 are adjacent points, not duplicate points. Their difference should look like an ordinary local step inside the image. A useful seam test therefore compares the wrap step against the distribution of neighbouring steps. Requiring literal equality over-penalizes valid high-frequency textures; accepting any small absolute difference over-rewards low-contrast blurred edges.

Our deterministic gate measures, independently on x and y:

• colour discontinuity at the wrap relative to ordinary adjacent-pixel change;
• first-derivative disagreement near the wrap relative to ordinary texture

gradients;

• the weakest boundary, because one good axis cannot hide one bad axis.

The four scores are combined geometrically and receive a weakest-axis penalty. The published score is deliberately interpretable as a gate, not advertised as a universal perceptual metric. A 2×2 preview remains part of every record because humans notice structured seams, lighting drift, and obvious repeated objects that a compact boundary metric can miss.

For a learned perceptual check, TexTile is the strongest directly relevant baseline we found. The CVPR 2024 paper introduces a differentiable tileability metric trained to distinguish tileable textures and shows how it can be used as an optimization objective. We are keeping our fast, deterministic gate as the always-available acceptance layer and treating TexTile as the higher-cost learned judge in offline dataset curation. That gives us an auditable fallback if a model download or GPU-side evaluator is unavailable.

What diffusion research says about the boundary

Three lines of work matter here.

Couple opposite sides during denoising

Tiled Diffusion (CVPR 2025) treats tile relationships as constraints inside latent diffusion. Its self-tiling configuration couples opposite sides with matched side identifiers and orientations. This is stronger than asking a text encoder to understand the word “seamless”: the sampler itself receives a relationship between boundaries.

The published implementation targets Stable Diffusion/SDXL rather than Z-Image. The transferable idea is the constraint, not a claim that its code can be pasted into a different transformer unchanged. A Z-Image port has to identify where the equivalent latent-side coupling belongs, verify scheduler conventions, and test whether it survives the VAE decode.

Make the denoising neighbourhood circular

Panorama pipelines have long used circular padding so the latent or decoded RGB wrap does not expose a left/right seam. Hugging Face's MultiDiffusion panorama documentation describes circular padding as the mechanism that closes the panorama boundary. For textures we need both axes, not only horizontal wrap.

There is an important practical warning. The Pattern Diffusion model card reports that applying circular convolution padding for the entire trajectory hurt its measured image quality. Its practical recipe rolls noise during the first 80% of sampling and enables circular padding only for the final 20%. That is useful engineering evidence, but it is a model card rather than a peer-reviewed result, so we treat the percentages as a baseline to reproduce, not a law.

The underlying intuition is plausible: early denoising should be free to form global content; late denoising should close the topology and clean the seam. Our experiment matrix will sweep the switch point rather than hard-code 80/20.

Learn a distribution of local periodic patches

Infinite Texture fine-tunes a diffusion model per source texture and aggregates denoising scores over overlapping random crops. Random crops make the learned representation less attached to one fixed window and let the model synthesize larger non-stationary texture fields.

For a general texture LoRA, the relevant lesson is that crop origin should not be meaningful. On a torus, a cyclic shift is a lossless change of origin. We can turn one verified tile into many views without inventing a seam: roll by a random x/y offset, then crop or encode. This is more principled than ordinary padded augmentation, which can manufacture boundary pixels that never existed in the periodic signal.

The training data gate comes before the LoRA

A LoRA is an efficient way to teach a model a distribution. It is also an efficient way to amplify a dataset defect. If half the “seamless” examples have faint vertical joins, training longer does not solve the problem; it teaches the join as part of the concept.

Our Z-Image training API now has an explicit dataset_mode: "texture" contract on both the local trainer and the scale-to-zero RunPod worker. In that mode:

1. every input is decoded and scored before the base model is loaded;
2. examples below the configured tileability threshold are rejected;
3. the run refuses to start without at least two accepted tiles;
4. each cached latent receives a random cyclic x/y roll on every training step;
5. the ordinary Z-Image rectified-flow target is preserved.

The last point matters. We are not yet adding an invented “edge pixels must be equal” loss, because that objective is wrong for discrete periodic samples and could push the model toward blurred borders. Random toroidal translation is a clean invariance with no new target. A learned TexTile loss on predicted clean images is a promising later experiment, but it needs an ablation against quality, diversity, and convergence rather than an assumption that more losses are better.

The local and remote trainers use the stock Diffusers Z-Image transformer for backpropagation. The accelerated Cute/OmniServe path remains inference-only; its fused kernels and low-memory serving layout are not silently used for training. This split keeps the serving hot path fast while making the optimization graph conventional and inspectable.

Bootstrap with textures that are correct by construction

Before trusting a generator, we need positives whose periodicity is known. Procedural synthesis provides them cheaply.

A Fourier texture made from integer-frequency sine and cosine components is periodic by construction. So are carefully parameterized toroidal value fields, periodic Gabor sums, and lattice patterns whose periods divide the canvas. Hex and honeycomb motifs can be built from three oriented cosine fields. Brick, weave, dots, scales, and circuit grids can use modular coordinates. These are not substitutes for photographic material data, but they are valuable for:

• testing the scorer with known positives;
• creating a broad low-cost bootstrap corpus;
• anchoring geometric categories that image generators often distort;
• supplying exact examples while the learned generator improves;
• finding false negatives in the acceptance gate.

The app.nz worker can generate these without a GPU. It hashes the prompt and seed into palette and phase parameters, writes the tile, runs the same verifier, builds the 2×2 proof, computes the search descriptor, and publishes only after the full contract passes.

Post-processing: repair, then verify again

Diffusion candidates that narrowly fail receive a conservative periodic edge blend. Opposite edge bands are paired and gradually mixed toward their shared boundary. This is intentionally less ambitious than neural outpainting: it is deterministic, bounded, and easy to audit.

It can still damage a texture. A wide band can smear directional grain; a narrow band can leave structured lighting mismatch. Therefore fixup is metadata, not a hidden operation, and the result is measured again. A repaired candidate that still fails is never published. Future offline experiments can compare this baseline with Poisson blending, graph-cut quilting, TexTile-guided optimization, and late-stage latent constraint methods.

We also avoid using post-fixup success as the only LoRA dataset source. Otherwise the LoRA may learn the characteristic blur of our repair operator. The training manifest records provenance, source model, LoRA, seed, pre/post scores, and fixup version so dataset builders can select exact, native-pass, or repaired examples separately.

Search in a space where moving the seam changes nothing

A tile has no canonical origin. Shifting it 200 pixels right produces the same material, but a naïve pixel vector says it is very different. The index should respect the same toroidal symmetry as training.

The first production descriptor uses low-frequency RGB Fourier magnitudes. Cyclic translation changes Fourier phase but leaves magnitude unchanged, so the descriptor is invariant to moving the seam. It is small enough to compute on CPU during a large backfill and supports “find textures like this one” with cosine similarity.

This descriptor captures palette and frequency structure, not high-level semantics. Text search covers prompts and tags. A future multimodal index can average CLIP-like embeddings over several toroidal rolls or use a periodic crop ensemble, then store that semantic vector beside—rather than instead of—the spectral descriptor. Keeping the two signals separate makes failures legible: “same colour/frequency” and “same material meaning” are different retrieval questions.

Production scheduling and the backfill contract

Library growth must never make the image API worse. The native OmniServe gateway has four admission tiers: paid, subscription, free, and background. A background request receives all diffusion permits only when the GPU is otherwise idle. It does not rent overflow capacity. Interactive arrivals win the queue.

The texture worker talks to the loopback-only native endpoint with X-Omniserve-Tier: background. The native gateway accepts that privilege only from a direct loopback connection with no relayed proxy headers; public clients cannot declare themselves background or paid. Jobs live in SQLite with attempts, next-attempt timestamps, exponential retry, and status. A restart resumes queued work instead of losing an in-memory batch.

Backfill submission is separately authenticated and bounded to 500 prompts per request. Generated assets are content-addressed into app.nz's R2-backed static store, with immutable source tiles and PNG proof sheets. User Z-Image generations are charged only after a verified result is stored. Procedural jobs are free. FAL's dedicated Ideogram tiling route remains an explicit metered alternative, not a silent fallback that could create an uncontrolled bill.

The experiment we still need to run

The implementation establishes a safe baseline; it does not settle the research questions. The next controlled experiment should compare:

Each variant should use held-out prompts and seeds, then report deterministic seam score, TexTile score, aesthetic/semantic quality, diversity, latency, and VRAM. Human raters should see randomized 2×2 or 3×3 proofs, not isolated tiles. Categories need separate slices: stochastic materials such as stone may behave differently from strongly structured brick, weave, hex, or typography-like patterns.

We should also measure failure modes beyond the seam:

• repeated hero objects that make the wallpaper grid obvious;
• lighting gradients that are technically continuous but visually periodic;
• scale ambiguity and inconsistent texel density;
• directional materials whose grain bends at the wrap;
• near-duplicate library growth;
• post-fixup blur concentrated at the former boundary.

What “verified” means here

Verified means a published artifact passed a declared, versioned acceptance pipeline and exposes the evidence needed to inspect it. It does not mean every viewer will consider the repetition invisible at every scale. Texture quality has several axes: boundary continuity, stationarity, repetition salience, semantic fidelity, physical plausibility, and—in PBR use—cross-map consistency.

The current library solves the first deployment milestone: durable background generation, exact procedural bootstrapping, an objective seam gate, cyclic similarity, 2×2 evidence, and a texture-aware Z-Image LoRA training contract. PBR channel generation and cross-channel verification are natural extensions; the existing PATINA/FAL material path is useful there, but it should enter the same evidence pipeline rather than bypass it because the provider labels an output tileable.

That is the larger principle: “seamless” should be a tested property of an artifact, not an adjective in a prompt.