Tileset-Generator/design-document.md

Tileset Generator — Design Document
1. Overview

Tileset Generator is a simple browser-based image tool that lets a user upload an image and convert it into a tileable texture. The tool hides obvious seams by offsetting the image, blending or healing the exposed center seams, and exporting the result as a resized .webp texture suitable for games, web backgrounds, 3D materials, and UI art.

The tool should run fully client-side in the browser. No server upload is required.

2. Core User Flow
User opens the Tileset Generator page.
User uploads or drags in an image.
The app displays:
Original preview
Tileable preview
Repeated texture preview
The app shifts the image by 50% horizontally and vertically.
The app hides the newly exposed seams using a selected seam-repair method.
User adjusts settings:
Output size
Seam blend width
Repair strength
Export quality
Crop or fit behavior
User exports the result as a .webp file.
3. Primary Features
Image Upload

Supported formats:

.png
.jpg
.jpeg
.webp

Input methods:

File picker
Drag and drop
Optional paste from clipboard

The image should be processed locally using browser APIs.

Seam Offset

The standard tile-generation operation is a 50% offset:

Original image:

[A B]
[C D]

After 50% offset:

[D C]
[B A]

This moves the original outer edges into the center of the image, making seams visible and easier to hide.

User-facing option:

Offset Mode:
- Auto 50% offset
- Horizontal only
- Vertical only
- Custom offset

For V1, Auto 50% offset is enough.

Seam Hiding

The exposed seam appears as a vertical and horizontal cross through the center of the offset image.

V1 should use a simple but effective blend-based repair approach.

V1 Seam Repair Method

Use a soft blur/blend region around the center seams:

Define a seam band around the vertical center.
Define a seam band around the horizontal center.
Sample pixels from both sides of the seam.
Blend across the seam using a smooth falloff.
Optionally add subtle noise preservation to avoid overly blurry lines.

User controls:

Seam Width: 8–128 px
Blend Strength: 0–100%
Detail Preservation: Low / Medium / High

Default:

Seam Width: 32 px
Blend Strength: 70%
Detail Preservation: Medium
Repeated Preview

The app should show the generated texture repeated in a grid so the user can visually inspect tiling quality.

Preview modes:

Single Tile
2x2 Repeat
3x3 Repeat
4x4 Repeat

Default:

3x3 Repeat

This is critical because a texture can look good alone but fail when repeated.

Resize and Export

The user can export the final image as .webp.

Output size options:

Original Size
512 x 512
1024 x 1024
2048 x 2048
Custom Width / Height

Resize behavior:

Crop to Square
Fit Within Size
Stretch to Size
Keep Aspect Ratio

Default:

1024 x 1024
Crop to Square
WebP Quality: 90

Export filename pattern:

tileset-generator-[width]x[height].webp

Example:

tileset-generator-1024x1024.webp
4. Interface Layout
Suggested Layout
+------------------------------------------------------+
| Tileset Generator                                    |
| Upload image → Generate tileable WebP texture        |
+------------------------------------------------------+

+----------------------+-------------------------------+
| Controls             | Preview                       |
|                      |                               |
| Upload Image         | [ Single / Repeated Preview ] |
| Output Size          |                               |
| Seam Width           |                               |
| Blend Strength       |                               |
| Export Quality       |                               |
|                      |                               |
| [Generate] [Export]  |                               |
+----------------------+-------------------------------+
Control Panel

Controls should appear in this order:

Upload image
Output size
Resize behavior
Seam width
Blend strength
Preview repeat count
WebP quality
Export button
5. Recommended Tech Stack

For a lightweight browser tool:

Vite + React + TypeScript
Canvas 2D API
browser-image-compression optional
FileSaver optional

Recommended stack:

React for UI
TypeScript for safer image-processing code
Canvas 2D API for pixel manipulation
OffscreenCanvas / Web Worker optional for larger images
WebP export via canvas.toBlob()

No backend required.

6. Image Processing Pipeline
Step 1 — Load Image
File → Object URL → ImageBitmap → Canvas

Use createImageBitmap() when available.

Step 2 — Normalize Image

Depending on the selected resize behavior:

Crop to square
Fit within output bounds
Stretch
Preserve aspect ratio

For texture generation, square textures are strongly preferred.

Recommended internal working size:

1024 x 1024 by default
Step 3 — Offset Image

Draw the source image into a new canvas in four wrapped quadrants.

Pseudo-code:

function offsetCanvas(source, offsetX, offsetY) {
  draw source shifted by offsetX / offsetY
  wrap overflowing regions to opposite edges
}

For 50% offset:

offsetX = width / 2
offsetY = height / 2
Step 4 — Repair Seam

Repair the vertical seam centered at:

x = width / 2

Repair the horizontal seam centered at:

y = height / 2

For each pixel inside the seam band:

distanceFromSeam = abs(pixelPosition - seamCenter)
blendAmount = 1 - smoothstep(0, seamWidth, distanceFromSeam)

Blend nearby pixels from both sides of the seam.

A simple practical V1 approach:

For each seam pixel:
- Sample left/right or top/bottom neighbor pixels
- Average them based on distance from seam center
- Mix the averaged color with the original pixel

This gives a soft seam-hiding effect without needing AI/inpainting.

Step 5 — Preview Repetition

Create a preview canvas or CSS background using the generated image.

For repeated preview:

background-image: url(generated-texture.webp);
background-repeat: repeat;
background-size: tileSize tileSize;

Canvas-based repeated preview is also fine.

Step 6 — Export WebP

Use:

canvas.toBlob(
  blob => saveBlob(blob, filename),
  "image/webp",
  quality
);

Where quality is:

quality = userQuality / 100;
7. V1 Scope
Include in V1
Local image upload
Canvas-based 50% offset
Basic seam blending
Output resize options
Repeated texture preview
WebP export
Quality slider
Drag-and-drop support
Exclude from V1
AI inpainting
Multi-texture PBR export
Normal map generation
Roughness/metalness map generation
Batch processing
Account system
Server-side processing
8. Nice-to-Have Features

Good V2 additions:

Brush-based manual seam repair
Clone-stamp tool
Random patch sampling
Content-aware seam healing
Generate normal map
Generate roughness map
Batch export
Presets:
Pixel art
Stone
Fabric
Terrain
Sci-fi panel
Organic texture
Export as:
.webp
.png
.jpg
Save/load project settings
Before/after comparison slider
9. Data Model
type ResizeMode =
  | "crop-square"
  | "fit"
  | "stretch"
  | "keep-aspect";

type PreviewMode =
  | "single"
  | "repeat-2"
  | "repeat-3"
  | "repeat-4";

type TilesetSettings = {
  outputWidth: number;
  outputHeight: number;
  resizeMode: ResizeMode;
  seamWidth: number;
  blendStrength: number;
  detailPreservation: "low" | "medium" | "high";
  webpQuality: number;
  previewMode: PreviewMode;
};

Default settings:

const defaultSettings: TilesetSettings = {
  outputWidth: 1024,
  outputHeight: 1024,
  resizeMode: "crop-square",
  seamWidth: 32,
  blendStrength: 70,
  detailPreservation: "medium",
  webpQuality: 90,
  previewMode: "repeat-3",
};
10. Main Components
App
├── UploadPanel
├── SettingsPanel
├── PreviewPanel
│   ├── OriginalPreview
│   ├── TilePreview
│   └── RepeatedPreview
├── ExportPanel
└── ProcessingWorker optional
11. Performance Considerations

For V1, Canvas 2D is enough.

Recommended limits:

Max input image size: 4096 x 4096
Default working size: 1024 x 1024
Warning above: 2048 x 2048

For large files:

Downscale before seam repair.
Use createImageBitmap() for efficient decoding.
Consider Web Worker processing later.
Avoid repeatedly processing on every slider movement.
Debounce setting changes by 150–300 ms.
12. Error Handling

Show user-friendly errors for:

Unsupported file type
Image failed to load
Image too large
Browser does not support WebP export
Canvas export failed

Example messages:

This file type is not supported. Please upload a PNG, JPG, or WebP image.
This image is very large. The tool will resize it before processing.
13. Export Behavior

Export button should be disabled until:

An image is uploaded
Processing is complete
A valid output size exists

Export metadata:

Format: WebP
Quality: user-selected
Dimensions: user-selected
Color space: browser default / sRGB
Transparency: preserve if source supports alpha
14. Practical V1 Algorithm
1. Load uploaded image.
2. Resize/crop to target working canvas.
3. Offset image by 50% width and 50% height.
4. Blend center vertical seam.
5. Blend center horizontal seam.
6. Display single and repeated previews.
7. Export final canvas as WebP.

Pseudo-code:

async function generateTileableTexture(file: File, settings: TilesetSettings) {
  const bitmap = await createImageBitmap(file);

  const normalizedCanvas = normalizeImage(bitmap, settings);
  const offsetCanvas = applyWrappedOffset(
    normalizedCanvas,
    settings.outputWidth / 2,
    settings.outputHeight / 2
  );

  const repairedCanvas = repairCenterSeams(offsetCanvas, {
    seamWidth: settings.seamWidth,
    blendStrength: settings.blendStrength,
    detailPreservation: settings.detailPreservation,
  });

  return repairedCanvas;
}
15. Success Criteria

The tool is successful when:

A user can upload an image and export a tileable .webp in under a minute.
The exported texture repeats without obvious hard seams.
The UI is understandable without instructions.
The tool runs fully in-browser.
The output is usable in game engines, websites, and 3D material workflows.
16. Suggested MVP Build Order
Build image upload and preview.
Add canvas normalization/resizing.
Implement 50% wrapped offset.
Add basic vertical/horizontal seam blend.
Add repeated preview.
Add WebP export.
Add settings controls.
Add drag-and-drop polish.
Add error handling.
Test with photos, fabric, stone, clouds, sci-fi panels, and terrain textures.