>,
-) -> Result<(), String> {
- let st = state.lock().unwrap();
- let tiles = st
- .sheet_tiles
- .as_ref()
- .ok_or("No sheet tiles available. Process a sheet first.")?;
-
- let gif_bytes = build_gif_bytes(tiles, &mode, row, fps)?;
- std::fs::write(&path, &gif_bytes).map_err(|e| format!("Failed to write GIF: {}", e))?;
- Ok(())
-}
-
-// ---------------------------------------------------------------------------
-// App setup
-// ---------------------------------------------------------------------------
-
-#[cfg_attr(mobile, tauri::mobile_entry_point)]
-pub fn run() {
- tauri::Builder::default()
- .plugin(tauri_plugin_dialog::init())
- .manage(Mutex::new(AppState::default()))
- .invoke_handler(tauri::generate_handler![
- open_image,
- process,
- get_image,
- save_image,
- list_palettes,
- fetch_lospec,
- get_palette_colors,
- load_palette_file,
- batch_process,
- sheet_preview,
- sheet_process,
- sheet_save_tiles,
- sheet_generate_gif,
- sheet_export_gif,
- ])
- .run(tauri::generate_context!())
- .expect("error while running tauri application");
-}
diff --git a/pixfix/ui/app.js b/pixfix/ui/app.js
deleted file mode 100644
index f669396..0000000
--- a/pixfix/ui/app.js
+++ /dev/null
@@ -1,1713 +0,0 @@
-// pixfix/ui/src/app.ts
-var { invoke } = window.__TAURI__.core;
-var { open: openDialog, save: saveDialog } = window.__TAURI__.dialog;
-var state = {
- activeTab: "preview",
- imageLoaded: false,
- imagePath: null,
- imageInfo: null,
- settingsFocusIndex: 0,
- processing: false,
- palettes: [],
- paletteIndex: 0,
- config: {
- gridSize: null,
- gridPhaseX: null,
- gridPhaseY: null,
- maxGridCandidate: 32,
- noGridDetect: false,
- downscaleMode: "snap",
- aaThreshold: null,
- paletteName: null,
- autoColors: null,
- lospecSlug: null,
- customPalette: null,
- noQuantize: false,
- removeBg: false,
- bgColor: null,
- borderThreshold: null,
- bgTolerance: 0.05,
- floodFill: true,
- outputScale: null,
- outputWidth: null,
- outputHeight: null
- },
- lospecResult: null,
- lospecError: null,
- lospecLoading: false,
- paletteColors: null,
- showAllHelp: false,
- lastProcessTime: null,
- batchFiles: [],
- batchOutputDir: null,
- batchRunning: false,
- batchProgress: null,
- batchResult: null,
- sheetMode: "auto",
- sheetConfig: {
- tileWidth: null,
- tileHeight: null,
- spacing: 0,
- margin: 0,
- separatorThreshold: 0.9,
- minSpriteSize: 8,
- pad: 0,
- noNormalize: false
- },
- sheetPreview: null,
- sheetProcessing: false,
- gifMode: "row",
- gifRow: 0,
- gifFps: 10,
- gifPreviewUrl: null,
- gifGenerating: false
-};
-var DEFAULT_CONFIG = JSON.parse(JSON.stringify(state.config));
-var DOWNSCALE_MODES = ["snap", "center-weighted", "majority-vote", "center-pixel"];
-function getSettings() {
- const c = state.config;
- return [
- { section: "Grid Detection" },
- {
- key: "gridSize",
- label: "Grid Size",
- value: c.gridSize === null ? "auto" : String(c.gridSize),
- help: 'How many screen pixels make up one "logical" pixel in your art. Auto-detection works well for most images. Override if the grid looks wrong.',
- changed: c.gridSize !== null
- },
- {
- key: "gridPhaseX",
- label: "Phase X",
- value: c.gridPhaseX === null ? "auto" : String(c.gridPhaseX),
- help: "Override the X offset of the grid alignment. Usually auto-detected.",
- changed: c.gridPhaseX !== null
- },
- {
- key: "gridPhaseY",
- label: "Phase Y",
- value: c.gridPhaseY === null ? "auto" : String(c.gridPhaseY),
- help: "Override the Y offset of the grid alignment. Usually auto-detected.",
- changed: c.gridPhaseY !== null
- },
- {
- key: "noGridDetect",
- label: "Skip Grid",
- value: c.noGridDetect ? "on" : "off",
- help: "Skip grid detection entirely. Useful if your image is already at logical resolution.",
- changed: c.noGridDetect
- },
- {
- key: "maxGridCandidate",
- label: "Max Grid",
- value: String(c.maxGridCandidate),
- help: "Maximum grid size to test during auto-detection (default: 32).",
- changed: c.maxGridCandidate !== 32
- },
- {
- key: "downscaleMode",
- label: "Mode",
- value: c.downscaleMode,
- help: 'How to combine pixels in each grid cell. "snap" cleans in-place at original resolution. Others reduce to logical pixel resolution.',
- changed: c.downscaleMode !== "snap"
- },
- { section: "Anti-Aliasing" },
- {
- key: "aaThreshold",
- label: "AA Removal",
- value: c.aaThreshold === null ? "off" : c.aaThreshold.toFixed(2),
- help: "Removes soft blending between colors added by AI generators. Lower values are more aggressive. Try 0.30\u20130.50 for most images.",
- changed: c.aaThreshold !== null
- },
- { section: "Color Palette" },
- {
- key: "paletteName",
- label: "Palette",
- value: c.paletteName === null ? "none" : c.paletteName,
- help: "Snap all colors to a classic pixel art palette. Mutually exclusive with Lospec and Auto Colors.",
- changed: c.paletteName !== null
- },
- {
- key: "lospecSlug",
- label: "Lospec",
- value: c.lospecSlug === null ? "none" : c.lospecSlug,
- help: 'Load any palette from lospec.com by slug (e.g. "pico-8", "endesga-32"). Press Enter to type a slug and fetch it.',
- changed: c.lospecSlug !== null
- },
- {
- key: "autoColors",
- label: "Auto Colors",
- value: c.autoColors === null ? "off" : String(c.autoColors),
- help: "Auto-extract the best N colors from your image using k-means clustering in OKLAB color space.",
- changed: c.autoColors !== null
- },
- {
- key: "paletteFile",
- label: "Load .hex",
- value: c.customPalette && !c.lospecSlug ? `${c.customPalette.length} colors` : "none",
- help: "Load a palette from a .hex file (one hex color per line). Overrides palette and auto colors.",
- changed: c.customPalette !== null && c.lospecSlug === null
- },
- {
- key: "noQuantize",
- label: "Skip Quantize",
- value: c.noQuantize ? "on" : "off",
- help: "Skip color quantization entirely. Useful if you only want grid snapping and AA removal without palette changes.",
- changed: c.noQuantize
- },
- { section: "Background" },
- {
- key: "removeBg",
- label: "Remove BG",
- value: c.removeBg ? "on" : "off",
- help: "Detect and make the background transparent. The dominant border color is treated as background.",
- changed: c.removeBg
- },
- {
- key: "bgColor",
- label: "BG Color",
- value: c.bgColor === null ? "auto" : c.bgColor,
- help: 'Explicit background color as hex (e.g. "#FF00FF"). If auto, detects from border pixels.',
- changed: c.bgColor !== null
- },
- {
- key: "borderThreshold",
- label: "Border Thresh",
- value: c.borderThreshold === null ? "0.40" : c.borderThreshold.toFixed(2),
- help: "Fraction of border pixels that must match for auto-detection (0.0\u20131.0, default: 0.40).",
- changed: c.borderThreshold !== null
- },
- {
- key: "bgTolerance",
- label: "BG Tolerance",
- value: c.bgTolerance.toFixed(2),
- help: "How different a pixel can be from the background color and still count as background. Higher = more aggressive.",
- changed: c.bgTolerance !== 0.05
- },
- {
- key: "floodFill",
- label: "Flood Fill",
- value: c.floodFill ? "on" : "off",
- help: "On: only remove connected background from edges. Off: remove matching color everywhere.",
- changed: !c.floodFill
- },
- { section: "Output" },
- {
- key: "outputScale",
- label: "Scale",
- value: c.outputScale === null ? "off" : c.outputScale + "x",
- help: "Scale the output by an integer multiplier (2x, 3x, etc). Great for upscaling sprites for game engines.",
- changed: c.outputScale !== null
- },
- {
- key: "outputWidth",
- label: "Width",
- value: c.outputWidth === null ? "auto" : String(c.outputWidth),
- help: "Explicit output width in pixels. Overrides scale.",
- changed: c.outputWidth !== null
- },
- {
- key: "outputHeight",
- label: "Height",
- value: c.outputHeight === null ? "auto" : String(c.outputHeight),
- help: "Explicit output height in pixels. Overrides scale.",
- changed: c.outputHeight !== null
- }
- ];
-}
-function getSettingRows() {
- return getSettings().filter((s) => !s.section);
-}
-function adjustSetting(key, direction) {
- const c = state.config;
- switch (key) {
- case "gridSize":
- if (c.gridSize === null) {
- c.gridSize = state.imageInfo?.gridSize || 4;
- } else {
- c.gridSize = Math.max(1, c.gridSize + direction);
- if (c.gridSize === 1 && direction < 0)
- c.gridSize = null;
- }
- break;
- case "gridPhaseX":
- if (c.gridPhaseX === null) {
- c.gridPhaseX = 0;
- } else {
- c.gridPhaseX = Math.max(0, c.gridPhaseX + direction);
- }
- break;
- case "gridPhaseY":
- if (c.gridPhaseY === null) {
- c.gridPhaseY = 0;
- } else {
- c.gridPhaseY = Math.max(0, c.gridPhaseY + direction);
- }
- break;
- case "maxGridCandidate":
- c.maxGridCandidate = Math.max(2, Math.min(64, c.maxGridCandidate + direction * 4));
- break;
- case "noGridDetect":
- c.noGridDetect = !c.noGridDetect;
- break;
- case "downscaleMode": {
- let idx = DOWNSCALE_MODES.indexOf(c.downscaleMode);
- idx = (idx + direction + DOWNSCALE_MODES.length) % DOWNSCALE_MODES.length;
- c.downscaleMode = DOWNSCALE_MODES[idx];
- break;
- }
- case "aaThreshold":
- if (c.aaThreshold === null) {
- c.aaThreshold = 0.5;
- } else {
- c.aaThreshold = Math.round((c.aaThreshold + direction * 0.05) * 100) / 100;
- if (c.aaThreshold <= 0)
- c.aaThreshold = null;
- else if (c.aaThreshold > 1)
- c.aaThreshold = 1;
- }
- break;
- case "paletteName": {
- const names = [null, ...state.palettes.map((p) => p.slug)];
- let idx = names.indexOf(c.paletteName);
- idx = (idx + direction + names.length) % names.length;
- c.paletteName = names[idx];
- if (c.paletteName !== null) {
- c.autoColors = null;
- c.lospecSlug = null;
- c.customPalette = null;
- state.lospecResult = null;
- fetchPaletteColors(c.paletteName);
- } else {
- state.paletteColors = null;
- }
- break;
- }
- case "autoColors":
- if (c.autoColors === null) {
- c.autoColors = 16;
- } else {
- c.autoColors = Math.max(2, c.autoColors + direction * 2);
- if (c.autoColors <= 2 && direction < 0)
- c.autoColors = null;
- else if (c.autoColors > 256)
- c.autoColors = 256;
- }
- if (c.autoColors !== null) {
- c.paletteName = null;
- c.lospecSlug = null;
- c.customPalette = null;
- state.paletteColors = null;
- state.lospecResult = null;
- }
- break;
- case "removeBg":
- c.removeBg = !c.removeBg;
- break;
- case "borderThreshold":
- if (c.borderThreshold === null) {
- c.borderThreshold = 0.4;
- } else {
- c.borderThreshold = Math.round((c.borderThreshold + direction * 0.05) * 100) / 100;
- if (c.borderThreshold <= 0)
- c.borderThreshold = null;
- else if (c.borderThreshold > 1)
- c.borderThreshold = 1;
- }
- break;
- case "bgTolerance":
- c.bgTolerance = Math.round((c.bgTolerance + direction * 0.01) * 100) / 100;
- c.bgTolerance = Math.max(0.01, Math.min(0.5, c.bgTolerance));
- break;
- case "floodFill":
- c.floodFill = !c.floodFill;
- break;
- case "outputScale":
- if (c.outputScale === null) {
- c.outputScale = 2;
- } else {
- c.outputScale = c.outputScale + direction;
- if (c.outputScale < 2)
- c.outputScale = null;
- else if (c.outputScale > 16)
- c.outputScale = 16;
- }
- break;
- case "outputWidth":
- if (c.outputWidth === null) {
- c.outputWidth = state.imageInfo?.width || 64;
- } else {
- c.outputWidth = Math.max(1, c.outputWidth + direction * 8);
- }
- break;
- case "outputHeight":
- if (c.outputHeight === null) {
- c.outputHeight = state.imageInfo?.height || 64;
- } else {
- c.outputHeight = Math.max(1, c.outputHeight + direction * 8);
- }
- break;
- }
-}
-async function fetchPaletteColors(slug) {
- try {
- const colors = await invoke("get_palette_colors", { slug });
- state.paletteColors = colors;
- renderSettings();
- } catch {
- state.paletteColors = null;
- }
-}
-async function fetchLospec(slug) {
- state.lospecLoading = true;
- state.lospecError = null;
- renderSettings();
- try {
- const result = await invoke("fetch_lospec", { slug });
- state.lospecResult = result;
- state.config.lospecSlug = slug;
- state.config.customPalette = result.colors;
- state.config.paletteName = null;
- state.config.autoColors = null;
- state.paletteColors = result.colors;
- state.lospecLoading = false;
- renderSettings();
- autoProcess();
- } catch (e) {
- state.lospecError = String(e);
- state.lospecLoading = false;
- renderSettings();
- }
-}
-async function loadPaletteFileDialog() {
- try {
- const result = await openDialog({
- multiple: false,
- filters: [{
- name: "Palette Files",
- extensions: ["hex", "txt"]
- }]
- });
- if (result) {
- const colors = await invoke("load_palette_file", { path: result });
- state.config.customPalette = colors;
- state.config.paletteName = null;
- state.config.autoColors = null;
- state.config.lospecSlug = null;
- state.lospecResult = null;
- state.paletteColors = colors;
- renderSettings();
- autoProcess();
- }
- } catch (e) {
- setStatus("Error loading palette: " + e, "error");
- }
-}
-function setStatus(msg, type = "") {
- const el = document.getElementById("status-msg");
- el.textContent = msg;
- el.className = "status-msg" + (type ? " " + type : "");
- const spinner = document.getElementById("status-spinner");
- if (type === "processing") {
- spinner.classList.add("active");
- } else {
- spinner.classList.remove("active");
- }
-}
-function showWelcomeLoading() {
- document.getElementById("welcome-loading").style.display = "flex";
-}
-function hideWelcomeLoading() {
- document.getElementById("welcome-loading").style.display = "none";
-}
-function switchTab(name) {
- state.activeTab = name;
- document.querySelectorAll(".tab").forEach((t) => {
- t.classList.toggle("active", t.dataset.tab === name);
- });
- document.querySelectorAll(".tab-panel").forEach((p) => {
- p.classList.toggle("active", p.id === "panel-" + name);
- });
- if (name === "batch")
- renderBatch();
- if (name === "sheet")
- renderSheet();
-}
-var SELECT_SETTINGS = ["downscaleMode", "paletteName"];
-var BOOLEAN_SETTINGS = ["removeBg", "floodFill", "noGridDetect", "noQuantize"];
-var INPUT_SETTINGS = ["gridSize", "gridPhaseX", "gridPhaseY", "maxGridCandidate", "aaThreshold", "autoColors", "bgColor", "borderThreshold", "bgTolerance", "lospecSlug", "outputScale", "outputWidth", "outputHeight"];
-var FILE_SETTINGS = ["paletteFile"];
-var NULLABLE_SETTINGS = {
- gridSize: { offLabel: "auto", defaultValue: () => state.imageInfo?.gridSize || 4 },
- gridPhaseX: { offLabel: "auto", defaultValue: () => 0 },
- gridPhaseY: { offLabel: "auto", defaultValue: () => 0 },
- aaThreshold: { offLabel: "off", defaultValue: () => 0.5 },
- autoColors: { offLabel: "off", defaultValue: () => 16 },
- lospecSlug: { offLabel: "none", defaultValue: () => null },
- bgColor: { offLabel: "auto", defaultValue: () => null },
- borderThreshold: { offLabel: "0.40", defaultValue: () => 0.4 },
- outputScale: { offLabel: "off", defaultValue: () => 2 },
- outputWidth: { offLabel: "auto", defaultValue: () => state.imageInfo?.width || 64 },
- outputHeight: { offLabel: "auto", defaultValue: () => state.imageInfo?.height || 64 }
-};
-function renderSettings() {
- const list = document.getElementById("settings-list");
- const focused = document.activeElement;
- if (focused && focused.classList?.contains("setting-inline-input") && list.contains(focused)) {
- updateSettingsFocusOnly(list);
- return;
- }
- const settings = getSettings();
- let rowIndex = 0;
- let html = "";
- for (const s of settings) {
- if (s.section) {
- html += `${s.section}
`;
- } else {
- const isFocused = rowIndex === state.settingsFocusIndex ? " focused" : "";
- const changed = s.changed ? " changed" : "";
- html += ``;
- html += `▶ `;
- html += `${s.label} `;
- html += ``;
- if (SELECT_SETTINGS.includes(s.key)) {
- html += renderInlineSelect(s.key);
- } else if (BOOLEAN_SETTINGS.includes(s.key)) {
- html += `${escapeHtml(s.value)} `;
- } else if (FILE_SETTINGS.includes(s.key)) {
- if (s.changed) {
- html += escapeHtml(s.value);
- html += `\xD7 `;
- } else {
- html += `${escapeHtml(s.value)} `;
- }
- } else if (INPUT_SETTINGS.includes(s.key)) {
- html += renderInlineInput(s.key);
- if (s.key in NULLABLE_SETTINGS && s.changed) {
- const nullable = NULLABLE_SETTINGS[s.key];
- html += `\xD7 `;
- }
- } else {
- html += escapeHtml(s.value);
- }
- html += ` `;
- html += `
`;
- html += `${s.help}
`;
- if ((s.key === "paletteName" || s.key === "lospecSlug" || s.key === "paletteFile") && state.paletteColors && state.paletteColors.length > 0) {
- if (s.key === "paletteName" && state.config.paletteName !== null || s.key === "lospecSlug" && state.config.lospecSlug !== null || s.key === "paletteFile" && state.config.customPalette !== null && state.config.lospecSlug === null) {
- html += renderPaletteSwatches(state.paletteColors);
- }
- }
- if (s.key === "lospecSlug") {
- if (state.lospecLoading) {
- html += `Fetching palette...
`;
- } else if (state.lospecError) {
- html += `${escapeHtml(state.lospecError)}
`;
- } else if (state.lospecResult && state.config.lospecSlug) {
- html += `${escapeHtml(state.lospecResult.name)} \u2014 ${state.lospecResult.numColors} colors
`;
- }
- }
- rowIndex++;
- }
- }
- list.innerHTML = html;
-}
-function updateSettingsFocusOnly(list) {
- const rows = list.querySelectorAll(".setting-row");
- rows.forEach((row, i) => {
- row.classList.toggle("focused", i === state.settingsFocusIndex);
- });
-}
-function renderPaletteSwatches(colors) {
- let html = '';
- for (const color of colors) {
- html += `
`;
- }
- html += "
${m} `).join("");
- return `${opts} `;
- }
- case "paletteName": {
- let opts = `none `;
- opts += state.palettes.map((p) => `${p.slug} (${p.numColors}) `).join("");
- return `${opts} `;
- }
- default:
- return "";
- }
-}
-function renderInlineInput(key) {
- const c = state.config;
- switch (key) {
- case "gridSize": {
- const val = c.gridSize === null ? "" : c.gridSize;
- return `No image loaded
';
- document.getElementById("diag-grid-bars").innerHTML = "";
- document.getElementById("diag-info").innerHTML = "";
- document.getElementById("diag-histogram").innerHTML = "";
- return;
- }
- let gridHtml = "";
- gridHtml += `Detected size ${info.gridSize ?? "none"}
`;
- gridHtml += `Confidence ${info.gridConfidence != null ? (info.gridConfidence * 100).toFixed(1) + "%" : "n/a"}
`;
- document.getElementById("diag-grid-info").innerHTML = gridHtml;
- let barsHtml = "";
- if (info.gridScores && info.gridScores.length > 0) {
- const maxScore = Math.max(...info.gridScores.map((s) => s[1]));
- const bestSize = info.gridSize;
- for (const [size, score] of info.gridScores) {
- const pct = maxScore > 0 ? score / maxScore * 100 : 0;
- const best = size === bestSize ? " best" : "";
- barsHtml += ``;
- barsHtml += `
${size} `;
- barsHtml += `
`;
- barsHtml += `
${score.toFixed(3)} `;
- barsHtml += `
Dimensions ${info.width} x ${info.height}
`;
- infoHtml += `Unique colors ${info.uniqueColors}
`;
- document.getElementById("diag-info").innerHTML = infoHtml;
- let histHtml = "";
- if (info.histogram) {
- for (const entry of info.histogram) {
- histHtml += ``;
- histHtml += `
`;
- histHtml += `
${entry.hex} `;
- histHtml += `
`;
- histHtml += `
${entry.percent.toFixed(1)}% `;
- histHtml += `
';
- html += '
Batch Processing
';
- html += '
Process multiple images with the current pipeline settings.
';
- html += "
';
- html += `
Files ${state.batchFiles.length} selected `;
- html += `Add Files `;
- if (state.batchFiles.length > 0) {
- html += `Clear `;
- }
- html += "
";
- if (state.batchFiles.length > 0) {
- html += '
';
- for (const f of state.batchFiles) {
- const name = f.split("/").pop().split("\\").pop();
- html += `
${escapeHtml(name)}
`;
- }
- html += "
";
- }
- html += "
';
- html += `
Output ${state.batchOutputDir ? escapeHtml(state.batchOutputDir.split("/").pop().split("\\").pop()) : "not set"} `;
- html += `Choose Folder `;
- html += "
";
- html += "
';
- html += `Process All `;
- html += "
";
- if (state.batchProgress) {
- const pct = Math.round(state.batchProgress.current / state.batchProgress.total * 100);
- html += '';
- html += `
${state.batchProgress.current}/${state.batchProgress.total} — ${escapeHtml(state.batchProgress.filename)}
`;
- html += `
`;
- html += "
';
- html += `
${r.succeeded} succeeded`;
- if (r.failed.length > 0) {
- html += `, ${r.failed.length} failed `;
- }
- html += "
";
- if (r.failed.length > 0) {
- html += '
';
- for (const f of r.failed) {
- const name = f.path.split("/").pop().split("\\").pop();
- html += `
${escapeHtml(name)}: ${escapeHtml(f.error)}
`;
- }
- html += "
";
- }
- html += "
';
- html += '
Sprite Sheet Processing
';
- html += '
Split a sprite sheet into individual tiles, run the normalize pipeline on each one, then reassemble into a clean sheet. You can also export each tile as a separate file or generate an animated GIF.
';
- if (!state.imageLoaded) {
- html += '
Load an image first in the Preview tab.
';
- }
- html += "
';
- html += '
Split Mode
';
- html += '
';
- html += `Fixed Grid `;
- html += `Auto-Split `;
- html += "
";
- if (state.sheetMode === "fixed") {
- html += '
Use when your sheet has a uniform grid — all tiles are the same size with consistent spacing.
';
- } else {
- html += '
Use when tiles are different sizes or irregularly placed. Detects sprites automatically by finding separator rows/columns. Sprites must be on a pure white background.
';
- }
- html += "
';
- if (state.sheetMode === "fixed") {
- html += '
Tile Width ';
- html += `
`;
- html += '
Width of each tile in pixels. Required.
';
- html += '
Tile Height ';
- html += `
`;
- html += '
Height of each tile in pixels. Required.
';
- html += '
Spacing ';
- html += `
`;
- html += '
Gap between tiles in pixels. Set to 0 if tiles are packed edge-to-edge.
';
- html += '
Margin ';
- html += `
`;
- html += '
Border around the entire sheet in pixels. Usually 0.
';
- } else {
- html += '
Sep. Threshold ';
- html += `
`;
- html += '
How uniform a row/column must be to count as a separator (0–1). Higher = stricter. 0.90 works for most sheets.
';
- html += '
Min Sprite Size ';
- html += `
`;
- html += '
Ignore detected regions smaller than this many pixels. Filters out noise and tiny fragments.
';
- html += '
Padding ';
- html += `
`;
- html += '
Extra pixels to include around each detected sprite. Useful if auto-detection crops too tightly.
';
- }
- html += "
';
- html += '
Skip Normalize ';
- html += `${sc.noNormalize ? "on" : "off"}
`;
- html += '
When on, tiles are split and reassembled without running the pipeline. Useful for just extracting or rearranging tiles.
';
- html += "
';
- html += '
';
- html += `Preview Split `;
- html += `Process Sheet `;
- html += `Save Tiles `;
- html += "
";
- html += '
Preview Split shows how many tiles will be extracted. Process Sheet runs the normalize pipeline on each tile and reassembles. Save Tiles exports each tile as a separate PNG.
';
- html += "
';
- html += `
${p.tileCount} tiles — ${p.cols}\xD7${p.rows} grid — ${p.tileWidth}\xD7${p.tileHeight}px each
`;
- html += "
';
- html += '
GIF Animation
';
- html += '
Generate an animated GIF from the processed tiles. Preview it here or export to a file.
';
- html += '
Animate ';
- html += '
';
- html += `By Row `;
- html += `Entire Sheet `;
- html += "
";
- if (state.gifMode === "row") {
- html += '
Row ';
- html += `
`;
- html += `
Which row to animate (0\u2013${p.rows - 1}). Each row becomes one animation sequence.
`;
- }
- html += '
Frame Rate ';
- html += `
`;
- html += '
Frames per second (1\u2013100). 10 fps is a good default for pixel art animations.
';
- html += '
';
- html += `Preview GIF `;
- html += `Export GIF `;
- html += "
";
- if (state.gifGenerating) {
- html += '
Generating GIF...
';
- }
- if (state.gifPreviewUrl) {
- html += '
';
- html += `
`;
- html += "
";
- }
- html += "
,
+ /// Per-frame delay as (numerator, denominator) milliseconds, exactly as
+ /// decoded, so re-encoding preserves the original timing.
+ pub delays: Vec<(u32, u32)>,
+}
+
+/// The result of the animated pipeline: processed frames, original timing,
+/// and the shared grid plus first-frame diagnostics.
+pub struct AnimatedState {
+ pub frames: Vec,
+ pub delays: Vec<(u32, u32)>,
+ /// Input canvas dimensions (all frames share them).
+ pub original_width: u32,
+ pub original_height: u32,
+ /// The one grid applied to every frame (detected on the first).
+ pub grid: Option,
+ /// First-frame diagnostics, with color counts computed across ALL
+ /// frames (merged histograms).
+ pub diagnostics: PipelineDiagnostics,
+}
+
+/// Whether a byte buffer starts with a GIF signature.
+pub fn is_gif(bytes: &[u8]) -> bool {
+ bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a")
+}
+
+fn load_err(source: image::ImageError) -> NormalizeError {
+ NormalizeError::ImageLoad {
+ path: "".into(),
+ source,
+ }
+}
+
+fn encode_err(source: image::ImageError) -> NormalizeError {
+ NormalizeError::Encode {
+ path: "".into(),
+ source,
+ }
+}
+
+/// Decode a GIF (animated or not) into composited full frames with delays.
+pub fn decode_gif(bytes: &[u8]) -> Result {
+ let decoder = GifDecoder::new(Cursor::new(bytes)).map_err(load_err)?;
+ let raw = decoder.into_frames().collect_frames().map_err(load_err)?;
+
+ let mut frames = Vec::with_capacity(raw.len());
+ let mut delays = Vec::with_capacity(raw.len());
+ for frame in raw {
+ delays.push(frame.delay().numer_denom_ms());
+ frames.push(frame.into_buffer());
+ }
+ if frames.is_empty() {
+ return Err(NormalizeError::InvalidInput(
+ "GIF contains no frames".to_string(),
+ ));
+ }
+ let (w, h) = (frames[0].width(), frames[0].height());
+ if frames.iter().any(|f| f.width() != w || f.height() != h) {
+ return Err(NormalizeError::InvalidInput(
+ "GIF frames decoded to inconsistent dimensions".to_string(),
+ ));
+ }
+ Ok(AnimatedImage { frames, delays })
+}
+
+/// Encode frames as an infinitely looping animated GIF, preserving
+/// per-frame delays. Pure in-memory; the caller owns any file I/O.
+pub fn encode_gif(frames: &[RgbaImage], delays: &[(u32, u32)]) -> Result> {
+ let mut bytes = Vec::new();
+ {
+ let mut encoder = GifEncoder::new(&mut bytes);
+ encoder.set_repeat(Repeat::Infinite).map_err(encode_err)?;
+ for (i, image) in frames.iter().enumerate() {
+ let (num, den) = delays.get(i).copied().unwrap_or((100, 1));
+ let frame =
+ Frame::from_parts(image.clone(), 0, 0, Delay::from_numer_denom_ms(num, den));
+ encoder.encode_frame(frame).map_err(encode_err)?;
+ }
+ }
+ Ok(bytes)
+}
+
+/// Run the normalization pipeline over an animation with shared decisions:
+/// one grid (from the first frame), one background color (resolved once on
+/// the first frame), one palette (merged histogram across all frames).
+/// Stage order and mask semantics mirror [`crate::pipeline::run_pipeline`].
+pub fn run_pipeline_animated(
+ anim: AnimatedImage,
+ config: &PipelineConfig,
+) -> Result {
+ let AnimatedImage { frames, delays } = anim;
+ let Some(first) = frames.first() else {
+ return Err(NormalizeError::InvalidInput(
+ "animated GIF has no frames".to_string(),
+ ));
+ };
+ let (original_width, original_height) = (first.width(), first.height());
+ if frames
+ .iter()
+ .any(|f| f.width() != original_width || f.height() != original_height)
+ {
+ return Err(NormalizeError::InvalidInput(
+ "animated GIF frames have inconsistent dimensions".to_string(),
+ ));
+ }
+
+ // Stage 1 (once): grid detection on the first frame. The same grid is
+ // applied to every frame so blocks can never drift between frames; when
+ // detection declines, no frame is snapped — same as the still path.
+ let mut probe = PipelineState::new(first.clone());
+ if !config.grid.skip {
+ grid_detect::detect_grid(&mut probe, &config.grid)?;
+ } else if let Some(grid) = grid_detect::override_grid(&config.grid) {
+ grid.validate(original_width, original_height)?;
+ probe.grid = Some(grid);
+ }
+ let shared_grid = probe.grid;
+ let grid_diag = probe.diagnostics;
+
+ let used_snap_mode = config.downscale.mode == DownscaleMode::Snap;
+
+ // Stages 2-5 per frame. The background COLOR is resolved once, on the
+ // first frame post-AA (per-frame re-detection could flicker between
+ // colors); the mask is rebuilt per frame from that shared color, and
+ // chroma keys mask each frame as normal.
+ let mut shared_bg: Option = None;
+ let mut states: Vec = Vec::with_capacity(frames.len());
+ for (i, frame) in frames.into_iter().enumerate() {
+ let mut state = PipelineState::new(frame);
+ state.grid = shared_grid;
+
+ // Stage 2: AA removal.
+ if !config.aa.skip {
+ aa_removal::remove_aa(&mut state, &config.aa)?;
+ }
+
+ // Stage 3: background mask (shared color) + chroma keys, at full
+ // resolution. Nothing is cleared yet — masked pixels don't vote in
+ // the snap, and the mask is applied afterwards.
+ if i == 0 && config.background.enabled {
+ shared_bg = background::resolve_background(&state.image, &config.background);
+ if shared_bg.is_none() {
+ info!("No dominant border color detected, skipping background removal");
+ }
+ }
+ let mut removal_mask: Option> = None;
+ if let Some(ref bg) = shared_bg {
+ removal_mask = Some(background::build_bg_mask(
+ &state.image,
+ bg,
+ &config.background,
+ ));
+ state.diagnostics.detected_bg = Some([bg.color[0], bg.color[1], bg.color[2]]);
+ state.diagnostics.bg_coverage = Some(bg.coverage);
+ }
+ if !config.background.chroma_keys.is_empty() {
+ let chroma = background::build_chroma_mask(
+ &state.image,
+ &config.background.chroma_keys,
+ config.background.chroma_tolerance,
+ config.background.defringe,
+ );
+ removal_mask = Some(match removal_mask {
+ Some(mut m) => {
+ for (a, b) in m.iter_mut().zip(chroma) {
+ *a |= b;
+ }
+ m
+ }
+ None => chroma,
+ });
+ }
+ state.bg_mask = removal_mask;
+
+ // Stage 4: grid normalization (mask-aware).
+ if state.grid.is_some() {
+ downscale::majority_vote_downscale(&mut state, &config.downscale)?;
+ }
+
+ // Stage 5: apply the background mask.
+ if let Some(mask) = state.bg_mask.take() {
+ let removed = background::apply_bg_mask(&mut state.image, &mask);
+ state.diagnostics.bg_pixels_removed = Some(removed as u64);
+ }
+
+ states.push(state);
+ }
+
+ // Diagnostics: the first frame's per-frame stats plus the grid
+ // detection results from the probe run.
+ let mut diagnostics = states[0].diagnostics.clone();
+ diagnostics.grid_confidence = grid_diag.grid_confidence;
+ diagnostics.grid_scores = grid_diag.grid_scores;
+ diagnostics.grid_best_guess = grid_diag.grid_best_guess;
+
+ // Stage 6 (once): dither detection on the first post-snap frame; the
+ // pairs pin quantization centroids exactly as in the still path.
+ let mut dither_pairs: Vec = Vec::new();
+ if config.dither.enabled && !config.quantize.skip {
+ let grid_for_dither = if used_snap_mode { shared_grid } else { None };
+ dither_pairs =
+ dither::detect_dither_pairs(&states[0].image, grid_for_dither.as_ref(), &config.dither);
+ if !dither_pairs.is_empty() {
+ info!(pairs = dither_pairs.len(), "Detected dither pairs");
+ }
+ diagnostics.dither_pairs = dither_pairs
+ .iter()
+ .map(|p| (p.a_rgb, p.b_rgb, p.alternating))
+ .collect();
+ }
+
+ // Stage 7 (once): shared quantization. ONE histogram merged across all
+ // post-snap frames feeds palette extraction, and ONE matcher snaps
+ // every frame, so colors cannot flicker between per-frame palettes.
+ let mut frames: Vec = states.into_iter().map(|s| s.image).collect();
+ if !config.quantize.skip {
+ let merged = merged_histogram(&frames);
+ let unique_before = merged.unique_colors();
+ if let Some((palette_oklab, palette_rgba)) =
+ quantize::resolve_palette(&merged, &config.quantize, &dither_pairs)?
+ {
+ let mut matcher = PaletteMatcher::from_parts(palette_oklab, palette_rgba);
+ quantize::warn_collapsed_dither_pairs(&mut matcher, &dither_pairs);
+ for frame in &mut frames {
+ matcher.snap_image(frame);
+ }
+ let unique_after = merged_histogram(&frames).unique_colors();
+ diagnostics.unique_colors_before = Some(unique_before as u32);
+ diagnostics.unique_colors_after = Some(unique_after as u32);
+ info!(colors = unique_after, "Quantization complete (shared)");
+ }
+ }
+
+ // Stage 8: output sizing, identical per frame (integer re-upscale for
+ // reduced modes, then explicit target dimensions).
+ let frames = frames
+ .into_iter()
+ .map(|f| finalize_output_size(f, shared_grid, used_snap_mode, config))
+ .collect();
+
+ Ok(AnimatedState {
+ frames,
+ delays,
+ original_width,
+ original_height,
+ grid: shared_grid,
+ diagnostics,
+ })
+}
+
+/// Merged color histogram across all frames (counts summed).
+fn merged_histogram(frames: &[RgbaImage]) -> ColorHistogram {
+ ColorHistogram::from_pixels(frames.iter().flat_map(|f| f.pixels().map(|p| p.0)))
+}
+
+/// Mirror of `run_pipeline` stage 8 for one frame: reduced modes get the
+/// crisp integer re-upscale unless `logical_output`; explicit output
+/// dimensions always win as a final Nearest resize.
+fn finalize_output_size(
+ mut image: RgbaImage,
+ grid: Option,
+ used_snap_mode: bool,
+ config: &PipelineConfig,
+) -> RgbaImage {
+ if !used_snap_mode && !config.downscale.logical_output {
+ if let Some(grid) = grid {
+ let (fx, fy) = grid.upscale_factors();
+ if fx > 1 || fy > 1 {
+ image = integer_upscale(&image, fx, fy);
+ }
+ }
+ }
+ let out_w = config.output_width.unwrap_or(image.width());
+ let out_h = config.output_height.unwrap_or(image.height());
+ if image.width() != out_w || image.height() != out_h {
+ image = image::imageops::resize(&image, out_w, out_h, image::imageops::FilterType::Nearest);
+ }
+ image
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::pipeline::QuantizeConfig;
+ use image::Rgba;
+
+ const BASE: [Rgba; 4] = [
+ Rgba([255, 0, 0, 255]),
+ Rgba([0, 255, 0, 255]),
+ Rgba([0, 0, 255, 255]),
+ Rgba([255, 255, 0, 255]),
+ ];
+ const SQUARE: Rgba = Rgba([30, 30, 30, 255]);
+
+ /// One 8x8-cell frame at pitch 4: deterministic per-cell colors plus a
+ /// 2x2-cell dark square whose position moves with the frame index.
+ fn synthetic_frame(index: u32) -> RgbaImage {
+ let (cells, pitch) = (8u32, 4u32);
+ let size = cells * pitch;
+ let mut img = RgbaImage::new(size, size);
+ for y in 0..size {
+ for x in 0..size {
+ let (cx, cy) = ((x / pitch) as usize, (y / pitch) as usize);
+ img.put_pixel(x, y, BASE[(cy * 31 + cx * 17 + cy * cx * 7) % BASE.len()]);
+ }
+ }
+ let sq_cx = 1 + index; // moving square at cells (sq_cx..sq_cx+2, 2..4)
+ for y in (2 * pitch)..(4 * pitch) {
+ for x in (sq_cx * pitch)..((sq_cx + 2) * pitch) {
+ img.put_pixel(x, y, SQUARE);
+ }
+ }
+ img
+ }
+
+ fn synthetic_anim() -> AnimatedImage {
+ AnimatedImage {
+ frames: (0..3).map(synthetic_frame).collect(),
+ delays: vec![(100, 1), (200, 1), (50, 1)],
+ }
+ }
+
+ #[test]
+ fn test_animation_shares_grid_and_palette() {
+ let config = PipelineConfig {
+ quantize: QuantizeConfig {
+ num_colors: Some(4),
+ seed: 3,
+ ..Default::default()
+ },
+ ..Default::default()
+ };
+ let state = run_pipeline_animated(synthetic_anim(), &config).unwrap();
+
+ assert_eq!(state.frames.len(), 3, "frame count preserved");
+ assert_eq!(state.delays, vec![(100, 1), (200, 1), (50, 1)]);
+
+ let grid = state.grid.expect("grid detected once on the first frame");
+ assert!(
+ (grid.pitch_x - 4.0).abs() < 0.05,
+ "expected pitch ~4, got {}",
+ grid.pitch_x
+ );
+
+ // The shared palette must hold across the whole animation: the
+ // UNION of unique colors over all frames fits the budget. Five
+ // input colors quantized per frame could keep different survivors
+ // per frame and blow past it.
+ let mut union = std::collections::HashSet::new();
+ for frame in &state.frames {
+ for p in frame.pixels() {
+ union.insert(p.0);
+ }
+ }
+ assert!(
+ union.len() <= 4,
+ "union of colors across frames must fit the budget, got {}",
+ union.len()
+ );
+ }
+
+ #[test]
+ fn test_no_snap_when_detection_declines() {
+ // Uniform frames give detection nothing; no frame may be snapped
+ // and the input must pass through unscathed.
+ let frames: Vec = (0..2)
+ .map(|_| RgbaImage::from_pixel(16, 16, Rgba([128, 128, 128, 255])))
+ .collect();
+ let anim = AnimatedImage {
+ frames: frames.clone(),
+ delays: vec![(100, 1), (100, 1)],
+ };
+ let config = PipelineConfig {
+ quantize: QuantizeConfig {
+ skip: true,
+ ..Default::default()
+ },
+ ..Default::default()
+ };
+ let state = run_pipeline_animated(anim, &config).unwrap();
+ assert!(state.grid.is_none());
+ assert_eq!(state.frames, frames);
+ }
+
+ #[test]
+ fn test_delays_and_pixels_survive_encode_decode_roundtrip() {
+ let anim = synthetic_anim();
+ let bytes = encode_gif(&anim.frames, &anim.delays).unwrap();
+ assert!(is_gif(&bytes));
+
+ let decoded = decode_gif(&bytes).unwrap();
+ assert_eq!(decoded.frames.len(), 3);
+ for (i, (orig, dec)) in anim.delays.iter().zip(&decoded.delays).enumerate() {
+ assert_eq!(
+ orig.0 as u64 * dec.1 as u64,
+ dec.0 as u64 * orig.1 as u64,
+ "frame {} delay must survive the roundtrip ({:?} vs {:?})",
+ i,
+ orig,
+ dec
+ );
+ }
+ // Fully opaque frames with few colors encode with an exact palette,
+ // so decoding must reproduce the composited full frames verbatim.
+ for (i, (orig, dec)) in anim.frames.iter().zip(&decoded.frames).enumerate() {
+ assert_eq!(orig, dec, "frame {} pixels must roundtrip exactly", i);
+ }
+ }
+
+ #[test]
+ fn test_encode_is_deterministic() {
+ let anim = synthetic_anim();
+ let a = encode_gif(&anim.frames, &anim.delays).unwrap();
+ let b = encode_gif(&anim.frames, &anim.delays).unwrap();
+ assert_eq!(a, b, "same frames must encode to identical bytes");
+ }
+
+ #[test]
+ fn test_empty_animation_rejected() {
+ let anim = AnimatedImage {
+ frames: Vec::new(),
+ delays: Vec::new(),
+ };
+ assert!(matches!(
+ run_pipeline_animated(anim, &PipelineConfig::default()),
+ Err(NormalizeError::InvalidInput(_))
+ ));
+ }
+}
diff --git a/src/batch.rs b/src/batch.rs
index 79f758a..547424d 100644
--- a/src/batch.rs
+++ b/src/batch.rs
@@ -1,123 +1,379 @@
//! Batch processing: normalize multiple images in parallel.
+//!
+//! The library does no terminal I/O here — callers supply a progress sink
+//! (the CLI wires indicatif, pixfix wires app events), and every file's
+//! outcome is itemized in the result so front ends can report precisely.
use std::path::{Path, PathBuf};
-use anyhow::Result;
-use indicatif::{ProgressBar, ProgressStyle};
-use rayon::prelude::*;
-
-use crate::image_util::io::{load_image, save_image};
+use crate::error::{NormalizeError, Result};
+use crate::image_util::io::{load_image, save_image_atomic, OutputFormat};
+use crate::parallel::*;
+use crate::paths::{derive_output_path, OutputNaming};
use crate::pipeline::{run_pipeline, PipelineConfig};
+use crate::report::FileStatus;
+
+/// Image extensions batch processing picks up (matched case-insensitively).
+const IMAGE_EXTENSIONS: &[&str] = &["png", "jpg", "jpeg", "gif", "bmp", "webp"];
+
+/// Progress event delivered to the caller's sink (possibly from worker
+/// threads, in arbitrary order).
+#[derive(Debug, Clone)]
+pub enum BatchEvent {
+ Started {
+ total: usize,
+ },
+ FileDone {
+ index: usize,
+ input: PathBuf,
+ output: PathBuf,
+ },
+ FileSkipped {
+ index: usize,
+ input: PathBuf,
+ reason: String,
+ },
+ FileFailed {
+ index: usize,
+ input: PathBuf,
+ error: String,
+ },
+ Finished {
+ succeeded: usize,
+ failed: usize,
+ skipped: usize,
+ },
+}
+
+/// Batch behavior knobs.
+#[derive(Debug, Clone)]
+pub struct BatchOptions {
+ pub overwrite: bool,
+ /// Suffix appended to output stems (default "_normalized"; empty allowed).
+ pub suffix: String,
+ /// Recreate the inputs' relative directory structure under the output
+ /// directory instead of flattening to file stems.
+ pub preserve_dirs: bool,
+ pub format: OutputFormat,
+}
+
+impl Default for BatchOptions {
+ fn default() -> Self {
+ Self {
+ overwrite: false,
+ suffix: "_normalized".to_string(),
+ preserve_dirs: false,
+ format: OutputFormat::Png,
+ }
+ }
+}
-/// Result of a batch processing run.
+/// One file's outcome.
+#[derive(Debug, Clone)]
+pub struct BatchFileOutcome {
+ pub input: PathBuf,
+ pub output: Option,
+ pub status: FileStatus,
+ pub error: Option,
+}
+
+/// Result of a batch run. Outcomes preserve input order.
+#[derive(Debug)]
pub struct BatchResult {
- pub succeeded: u32,
- pub failed: Vec<(PathBuf, String)>,
+ pub files: Vec,
}
-/// Resolve a glob pattern or directory path into a list of image files.
-pub fn resolve_inputs(pattern: &str) -> Result> {
+impl BatchResult {
+ pub fn succeeded(&self) -> usize {
+ self.count(FileStatus::Ok)
+ }
+ pub fn failed(&self) -> usize {
+ self.count(FileStatus::Failed)
+ }
+ pub fn skipped(&self) -> usize {
+ self.count(FileStatus::Skipped)
+ }
+ fn count(&self, status: FileStatus) -> usize {
+ self.files.iter().filter(|f| f.status == status).count()
+ }
+}
+
+/// Resolved batch inputs plus the base directory relative paths are
+/// computed against for `preserve_dirs`.
+#[derive(Debug)]
+pub struct ResolvedInputs {
+ pub base: PathBuf,
+ pub files: Vec,
+}
+
+/// Resolve a glob pattern or directory path into a sorted list of image
+/// files. Extensions match case-insensitively (`.PNG` works).
+pub fn resolve_inputs(pattern: &str) -> Result {
let path = Path::new(pattern);
- // If it's a directory, glob for common image extensions inside it
+ // Directory: every image file directly inside it.
if path.is_dir() {
let mut files = Vec::new();
- for ext in &["png", "jpg", "jpeg", "gif", "bmp", "webp"] {
- let glob_pattern = format!("{}/*.{}", path.display(), ext);
- for entry in glob::glob(&glob_pattern)? {
- files.push(entry?);
+ let entries = std::fs::read_dir(path).map_err(|source| NormalizeError::Io {
+ path: path.to_path_buf(),
+ source,
+ })?;
+ for entry in entries {
+ let entry = entry.map_err(|source| NormalizeError::Io {
+ path: path.to_path_buf(),
+ source,
+ })?;
+ let p = entry.path();
+ if p.is_file() && has_image_extension(&p) {
+ files.push(p);
}
}
files.sort();
- return Ok(files);
+ return Ok(ResolvedInputs {
+ base: path.to_path_buf(),
+ files,
+ });
}
- // Otherwise treat as a glob pattern
- let mut files: Vec = glob::glob(pattern)?
+ // Otherwise treat as a glob pattern.
+ let mut files: Vec = glob::glob(pattern)
+ .map_err(|e| NormalizeError::InvalidInput(format!("bad glob pattern: {}", e)))?
.filter_map(|e| e.ok())
.filter(|p| p.is_file())
.collect();
files.sort();
- Ok(files)
+ Ok(ResolvedInputs {
+ base: glob_base(pattern),
+ files,
+ })
+}
+
+fn has_image_extension(path: &Path) -> bool {
+ path.extension()
+ .and_then(|e| e.to_str())
+ .map(|e| {
+ let lower = e.to_ascii_lowercase();
+ IMAGE_EXTENSIONS.contains(&lower.as_str())
+ })
+ .unwrap_or(false)
+}
+
+/// The non-glob directory prefix of a pattern ("sprites/**/*.png" ->
+/// "sprites"), used as the base for relative output paths.
+fn glob_base(pattern: &str) -> PathBuf {
+ let mut base = PathBuf::new();
+ for component in Path::new(pattern).iter() {
+ let s = component.to_string_lossy();
+ if s.contains(['*', '?', '[', '{']) {
+ break;
+ }
+ base.push(component);
+ }
+ // The last non-glob component may be the filename itself; only keep
+ // directories.
+ if base.as_os_str().is_empty() {
+ PathBuf::from(".")
+ } else if base.is_dir() {
+ base
+ } else {
+ base.parent()
+ .filter(|p| !p.as_os_str().is_empty())
+ .map(|p| p.to_path_buf())
+ .unwrap_or_else(|| PathBuf::from("."))
+ }
}
-/// Compute the output path for a batch-processed file.
-fn output_path_for(input: &Path, output_dir: &Path) -> PathBuf {
- let stem = input
- .file_stem()
- .unwrap_or_default()
- .to_string_lossy();
- let ext = input
- .extension()
- .unwrap_or_default()
- .to_string_lossy();
- let ext = if ext.is_empty() { "png" } else { &ext };
- output_dir.join(format!("{}_normalized.{}", stem, ext))
+/// Plan every output path up front and reject colliding ones — flattening
+/// `a/x.png` and `b/x.png` into one directory used to race two rayon
+/// workers onto the same file.
+pub fn plan_batch_outputs(
+ inputs: &ResolvedInputs,
+ output_dir: &Path,
+ opts: &BatchOptions,
+) -> Result> {
+ let naming = OutputNaming {
+ suffix: &opts.suffix,
+ extension: opts.format.extension(),
+ };
+ let outputs: Vec = inputs
+ .files
+ .iter()
+ .map(|input| {
+ if opts.preserve_dirs {
+ let rel_dir = input
+ .parent()
+ .and_then(|p| p.strip_prefix(&inputs.base).ok())
+ .unwrap_or(Path::new(""));
+ derive_output_path(input, Some(&output_dir.join(rel_dir)), &naming)
+ } else {
+ derive_output_path(input, Some(output_dir), &naming)
+ }
+ })
+ .collect();
+
+ let mut seen: std::collections::HashMap = std::collections::HashMap::new();
+ for (input, output) in inputs.files.iter().zip(&outputs) {
+ let key = output.to_string_lossy().to_lowercase();
+ if let Some(prev) = seen.insert(key, input) {
+ return Err(NormalizeError::InvalidInput(format!(
+ "output collision: {} and {} both map to {} — use --preserve-dirs or a \
+ different --suffix",
+ prev.display(),
+ input.display(),
+ output.display()
+ )));
+ }
+ }
+
+ Ok(outputs)
}
/// Process multiple images in parallel with a shared pipeline config.
-pub fn run_batch(
- inputs: &[PathBuf],
+///
+/// `progress` receives events from worker threads; outcomes come back in
+/// input order regardless. One bad file never aborts the run.
+pub fn run_batch(
+ inputs: &ResolvedInputs,
output_dir: &Path,
config: &PipelineConfig,
- overwrite: bool,
-) -> Result {
- let bar = ProgressBar::new(inputs.len() as u64);
- bar.set_style(
- ProgressStyle::default_bar()
- .template("[{elapsed_precise}] {bar:40.cyan/blue} {pos}/{len} {msg}")
- .unwrap()
- .progress_chars("##-"),
- );
-
- let results: Vec> = inputs
+ opts: &BatchOptions,
+ progress: F,
+) -> Result
+where
+ F: Fn(BatchEvent) + Sync,
+{
+ let outputs = plan_batch_outputs(inputs, output_dir, opts)?;
+
+ // Create any per-output directories up front (cheap, avoids races).
+ if opts.preserve_dirs {
+ for out in &outputs {
+ if let Some(parent) = out.parent() {
+ std::fs::create_dir_all(parent).map_err(|source| NormalizeError::Io {
+ path: parent.to_path_buf(),
+ source,
+ })?;
+ }
+ }
+ }
+
+ progress(BatchEvent::Started {
+ total: inputs.files.len(),
+ });
+
+ let files: Vec = inputs
+ .files
.par_iter()
- .map(|input_path| {
- let out = output_path_for(input_path, output_dir);
-
- if out.exists() && !overwrite {
- bar.inc(1);
- return Err((
- input_path.clone(),
- format!("Output already exists: {}", out.display()),
- ));
+ .zip(outputs.par_iter())
+ .enumerate()
+ .map(|(index, (input, output))| {
+ if output.exists() && !opts.overwrite {
+ let reason = "output already exists (use --overwrite)".to_string();
+ progress(BatchEvent::FileSkipped {
+ index,
+ input: input.clone(),
+ reason: reason.clone(),
+ });
+ return BatchFileOutcome {
+ input: input.clone(),
+ output: Some(output.clone()),
+ status: FileStatus::Skipped,
+ error: Some(reason),
+ };
}
- let result = (|| -> Result<(), String> {
- let image = load_image(input_path)
- .map_err(|e| format!("Failed to load: {}", e))?;
- let state = run_pipeline(image, config)
- .map_err(|e| format!("Pipeline failed: {}", e))?;
- save_image(&state.image, &out)
- .map_err(|e| format!("Failed to save: {}", e))?;
- Ok(())
+ let result = (|| -> Result<()> {
+ let image = load_image(input)?;
+ let state = run_pipeline(image, config)?;
+ save_image_atomic(&state.image, output, opts.format)
})();
- bar.inc(1);
-
match result {
Ok(()) => {
- bar.set_message(format!(
- "{}",
- input_path.file_name().unwrap_or_default().to_string_lossy()
- ));
- Ok(())
+ progress(BatchEvent::FileDone {
+ index,
+ input: input.clone(),
+ output: output.clone(),
+ });
+ BatchFileOutcome {
+ input: input.clone(),
+ output: Some(output.clone()),
+ status: FileStatus::Ok,
+ error: None,
+ }
+ }
+ Err(e) => {
+ progress(BatchEvent::FileFailed {
+ index,
+ input: input.clone(),
+ error: e.to_string(),
+ });
+ BatchFileOutcome {
+ input: input.clone(),
+ output: None,
+ status: FileStatus::Failed,
+ error: Some(e.to_string()),
+ }
}
- Err(e) => Err((input_path.clone(), e)),
}
})
.collect();
- bar.finish_with_message("done");
+ let result = BatchResult { files };
+ progress(BatchEvent::Finished {
+ succeeded: result.succeeded(),
+ failed: result.failed(),
+ skipped: result.skipped(),
+ });
- let mut succeeded = 0u32;
- let mut failed = Vec::new();
- for r in results {
- match r {
- Ok(()) => succeeded += 1,
- Err(e) => failed.push(e),
+ Ok(result)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn inputs(paths: &[&str]) -> ResolvedInputs {
+ ResolvedInputs {
+ base: PathBuf::from("in"),
+ files: paths.iter().map(PathBuf::from).collect(),
}
}
- Ok(BatchResult { succeeded, failed })
+ #[test]
+ fn test_collision_detected() {
+ let ins = inputs(&["in/a/x.png", "in/b/x.png"]);
+ let err = plan_batch_outputs(&ins, Path::new("out"), &BatchOptions::default());
+ assert!(matches!(err, Err(NormalizeError::InvalidInput(_))));
+ }
+
+ #[test]
+ fn test_preserve_dirs_resolves_collision() {
+ let ins = inputs(&["in/a/x.png", "in/b/x.png"]);
+ let opts = BatchOptions {
+ preserve_dirs: true,
+ ..Default::default()
+ };
+ let outs = plan_batch_outputs(&ins, Path::new("out"), &opts).unwrap();
+ assert_eq!(outs[0], PathBuf::from("out/a/x_normalized.png"));
+ assert_eq!(outs[1], PathBuf::from("out/b/x_normalized.png"));
+ }
+
+ #[test]
+ fn test_custom_suffix_and_format() {
+ let ins = inputs(&["in/cat.jpg"]);
+ let opts = BatchOptions {
+ suffix: String::new(),
+ format: OutputFormat::Webp,
+ ..Default::default()
+ };
+ let outs = plan_batch_outputs(&ins, Path::new("out"), &opts).unwrap();
+ assert_eq!(outs[0], PathBuf::from("out/cat.webp"));
+ }
+
+ #[test]
+ fn test_case_insensitive_extension() {
+ assert!(has_image_extension(Path::new("x.PNG")));
+ assert!(has_image_extension(Path::new("x.WebP")));
+ assert!(!has_image_extension(Path::new("x.txt")));
+ }
}
diff --git a/src/cli.rs b/src/cli.rs
index b88b4d2..15f9b98 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,9 +1,12 @@
use clap::{Parser, Subcommand};
use std::path::PathBuf;
+use crate::error::Result;
+use crate::pipeline::options::{PaletteSource, PipelineOptions};
+
#[derive(Parser, Debug)]
#[command(
- name = "normalize-pixelart",
+ name = "pixfix",
about = "Normalize AI-generated pixel art into clean, grid-aligned game assets",
version
)]
@@ -16,10 +19,19 @@ pub struct Cli {
#[arg(short, long, global = true)]
pub quiet: bool,
- /// Path to config file (default: .normalize-pixelart.toml in cwd)
+ /// Path to config file (default: .pixfix.toml in cwd)
#[arg(long, global = true)]
pub config: Option,
+ /// Ignore any config file, including one auto-discovered in the cwd
+ #[arg(long, global = true, conflicts_with = "config", hide_short_help = true)]
+ pub no_config: bool,
+
+ /// Emit one machine-readable JSON result document to stdout; progress
+ /// events go to stderr as NDJSON
+ #[arg(long, global = true)]
+ pub json: bool,
+
#[command(subcommand)]
pub command: Commands,
}
@@ -28,6 +40,8 @@ pub struct Cli {
pub enum Commands {
/// Process a single image
Process(ProcessArgs),
+ /// Inspect an image (grid, background, colors) without writing anything
+ Analyze(AnalyzeArgs),
/// Batch process a directory of images
Batch(BatchArgs),
/// Process a sprite sheet (split, normalize, reassemble)
@@ -39,6 +53,20 @@ pub enum Commands {
Tui(TuiArgs),
}
+#[derive(Parser, Debug)]
+pub struct AnalyzeArgs {
+ /// Input image path
+ pub input: PathBuf,
+
+ /// Also preview sprite-sheet auto-splitting (reports the sprite count)
+ #[arg(long)]
+ pub sheet: bool,
+
+ /// Pipeline options (grid overrides etc. are honored)
+ #[command(flatten)]
+ pub pipeline: PipelineFlags,
+}
+
#[cfg(feature = "tui")]
#[derive(Parser, Debug)]
pub struct TuiArgs {
@@ -51,78 +79,236 @@ pub struct TuiArgs {
}
/// Shared pipeline flags used by process, batch, and sheet commands.
+///
+/// Flags deliberately carry no clap defaults: an unset flag stays `None` so
+/// config-file values can fill in, and the hard defaults live in
+/// `PipelineOptions::into_config` only.
#[derive(Parser, Debug, Clone)]
+#[command(group = clap::ArgGroup::new("palette_source")
+ .multiple(false)
+ .conflicts_with("no_quantize"))]
pub struct PipelineFlags {
// --- Grid Detection ---
- /// Override auto-detected grid size (pixels per logical pixel)
+ /// Override auto-detected grid size in pixels per logical pixel
+ /// (fractional values like 10.667 are allowed)
#[arg(long)]
- pub grid_size: Option,
+ pub grid_size: Option,
/// Override grid phase offset as "X,Y" (default: auto-detect)
- #[arg(long, value_parser = parse_phase)]
+ #[arg(long, value_parser = parse_phase, requires = "grid_size", hide_short_help = true)]
pub grid_phase: Option<(u32, u32)>,
/// Skip grid detection entirely (requires --grid-size)
- #[arg(long)]
+ #[arg(long, requires = "grid_size", hide_short_help = true)]
pub no_grid_detect: bool,
- /// Maximum grid size candidate to test during detection (default: 32)
- #[arg(long, default_value = "32")]
- pub max_grid_candidate: u32,
+ /// Maximum grid size candidate to test during detection [default: 32]
+ #[arg(long, hide_short_help = true)]
+ pub max_grid_candidate: Option,
+
+ /// Multiply the final grid pitch (auto-detected or --grid-size) by an
+ /// integer. Detection finds the grid the generator rendered on; the
+ /// intended pixel-art resolution is often 2x or more coarser. Phase is
+ /// preserved so blocks stay aligned. No effect when detection declines.
+ #[arg(long, value_parser = clap::value_parser!(u32).range(1..))]
+ pub coarsen: Option,
+
+ /// Confidence floor (0.0-1.0) below which detection declines to snap
+ /// and only reports its best guess [default: 0.35]. Lower it to accept
+ /// shakier grids on heavily anti-aliased images; 0 accepts anything.
+ #[arg(long, hide_short_help = true)]
+ pub min_confidence: Option,
// --- Downscale ---
- /// Downscale mode: snap (default, preserves dithering), center-weighted, majority-vote, center-pixel
- #[arg(long, default_value = "snap")]
- pub downscale_mode: String,
+ /// Downscale mode [default: snap, which preserves dithering]
+ #[arg(long, value_enum)]
+ pub downscale_mode: Option,
+
+ /// Preserve original per-pixel alpha instead of binarizing each block
+ /// to fully opaque or fully transparent
+ #[arg(long, hide_short_help = true)]
+ pub keep_alpha: bool,
+
+ /// For reduced-resolution modes: output the true logical size instead
+ /// of the default crisp integer re-upscale
+ #[arg(long, hide_short_help = true)]
+ pub logical_size: bool,
// --- Anti-aliasing ---
/// Enable AA removal with sensitivity 0.0-1.0 (off by default).
- /// Lower = more aggressive. Only useful for cleanly upscaled pixel art.
+ /// Higher = more aggressive. Only useful for cleanly upscaled pixel art.
#[arg(long)]
pub aa_threshold: Option,
+ /// Maximum AA removal passes (wide AA ramps need several) [default: 3]
+ #[arg(long, requires = "aa_threshold", hide_short_help = true)]
+ pub aa_passes: Option,
+
// --- Color Quantization ---
- /// Use a predefined palette (pico-8, sweetie-16, endesga-32, endesga-64, gameboy, nes)
- #[arg(long)]
+ /// Use a predefined palette (see `palette list` for options)
+ #[arg(long, group = "palette_source", value_parser = parse_palette_name)]
pub palette: Option,
/// Load a custom palette from a .hex file (one color per line)
- #[arg(long)]
+ #[arg(long, group = "palette_source")]
pub palette_file: Option,
/// Fetch a palette from Lospec by slug (e.g., "sweetie-16", "endesga-32")
#[cfg(feature = "lospec")]
- #[arg(long)]
+ #[arg(long, group = "palette_source")]
pub lospec: Option,
/// Auto-extract palette with this many colors
- #[arg(long)]
+ #[arg(long, group = "palette_source")]
pub colors: Option,
/// Skip color quantization entirely
#[arg(long)]
pub no_quantize: bool,
+ /// RNG seed for palette extraction (same input + seed = identical output)
+ #[arg(long)]
+ pub seed: Option,
+
+ /// Disable dither preservation: no pair detection, no centroid pinning,
+ /// no AA dither guard — quantization may flatten dithered shading
+ #[arg(long, hide_short_help = true)]
+ pub flatten_dither: bool,
+
// --- Background Removal ---
/// Enable background detection and removal
- #[arg(long)]
+ #[arg(long, overrides_with = "no_remove_bg")]
pub remove_bg: bool,
+ /// Disable background removal (overrides a config file that enables it)
+ #[arg(long, overrides_with = "remove_bg", hide_short_help = true)]
+ pub no_remove_bg: bool,
+
/// Explicit background color as hex (e.g., "FF00FF" or "#FF00FF")
- #[arg(long)]
- pub bg_color: Option,
+ #[arg(long, value_parser = parse_hex_color_arg)]
+ pub bg_color: Option<[u8; 3]>,
- /// Minimum fraction of border pixels for auto-detection (0.0-1.0, default: 0.4)
- #[arg(long)]
+ /// Minimum fraction of border pixels for auto-detection (0.0-1.0) [default: 0.4]
+ #[arg(long, hide_short_help = true)]
pub bg_threshold: Option,
- /// Color tolerance for background matching in OKLAB space (default: 0.05)
- #[arg(long)]
+ /// Color tolerance for background matching in OKLAB space [default: 0.05]
+ #[arg(long, hide_short_help = true)]
pub bg_tolerance: Option,
+ /// Remove background with flood-fill from the border (the default)
+ #[arg(long, overrides_with = "no_flood_fill", hide_short_help = true)]
+ pub flood_fill: bool,
+
/// Use global replacement instead of flood-fill (removes interior bg too)
- #[arg(long)]
+ #[arg(long, overrides_with = "flood_fill", hide_short_help = true)]
pub no_flood_fill: bool,
+
+ // --- Chroma keying ---
+ /// Remove this color everywhere in the image (green-screen style; no
+ /// border detection, no flood fill). Repeat for multiple keys.
+ #[arg(long, value_parser = parse_hex_color_arg)]
+ pub chroma_key: Vec<[u8; 3]>,
+
+ /// OKLAB match tolerance for chroma keys [default: 0.05]
+ #[arg(long, requires = "chroma_key", hide_short_help = true)]
+ pub chroma_tolerance: Option,
+}
+
+impl PipelineFlags {
+ /// Lower CLI flags into pipeline options.
+ ///
+ /// Does the palette-file / Lospec I/O up front so bad palettes fail before
+ /// any image is loaded.
+ pub fn to_options(&self) -> Result {
+ // Palette source precedence within the CLI layer:
+ // --palette-file > --lospec > --palette > --colors.
+ let palette = if let Some(ref path) = self.palette_file {
+ let colors = crate::color::palettes::load_hex_file(path)?;
+ Some(PaletteSource::Custom {
+ colors,
+ label: Some(format!("file:{}", path.display())),
+ })
+ } else if let Some(slug) = self.lospec_slug() {
+ #[cfg(feature = "lospec")]
+ {
+ let pal = crate::color::lospec::fetch_lospec_palette(slug, false)?;
+ Some(PaletteSource::Custom {
+ colors: pal.colors,
+ label: Some(format!("lospec:{}", pal.slug)),
+ })
+ }
+ #[cfg(not(feature = "lospec"))]
+ {
+ let _ = slug;
+ None
+ }
+ } else if let Some(ref name) = self.palette {
+ Some(PaletteSource::Named(name.clone()))
+ } else {
+ self.colors.map(PaletteSource::AutoExtract)
+ };
+
+ Ok(PipelineOptions {
+ grid_size: self.grid_size,
+ grid_phase: self.grid_phase,
+ max_grid_candidate: self.max_grid_candidate,
+ no_grid_detect: self.no_grid_detect.then_some(true),
+ coarsen: self.coarsen,
+ min_confidence: self.min_confidence,
+ downscale_mode: self.downscale_mode,
+ keep_alpha: self.keep_alpha.then_some(true),
+ logical_output: self.logical_size.then_some(true),
+ aa_threshold: self.aa_threshold,
+ aa_skip: self.aa_threshold.map(|_| false),
+ aa_passes: self.aa_passes,
+ palette,
+ no_quantize: self.no_quantize.then_some(true),
+ seed: self.seed,
+ flatten_dither: self.flatten_dither.then_some(true),
+ bg_enabled: self.bg_enabled(),
+ bg_color: self.bg_color,
+ bg_border_threshold: self.bg_threshold,
+ bg_color_tolerance: self.bg_tolerance,
+ bg_flood_fill: self.flood_fill_enabled(),
+ chroma_keys: (!self.chroma_key.is_empty()).then(|| self.chroma_key.clone()),
+ chroma_tolerance: self.chroma_tolerance,
+ output_width: None,
+ output_height: None,
+ })
+ }
+
+ /// Tri-state from the --remove-bg / --no-remove-bg pair.
+ pub fn bg_enabled(&self) -> Option {
+ if self.remove_bg {
+ Some(true)
+ } else if self.no_remove_bg {
+ Some(false)
+ } else {
+ None
+ }
+ }
+
+ /// Tri-state from the --flood-fill / --no-flood-fill pair.
+ pub fn flood_fill_enabled(&self) -> Option {
+ if self.flood_fill {
+ Some(true)
+ } else if self.no_flood_fill {
+ Some(false)
+ } else {
+ None
+ }
+ }
+
+ #[cfg(feature = "lospec")]
+ fn lospec_slug(&self) -> Option<&str> {
+ self.lospec.as_deref()
+ }
+
+ #[cfg(not(feature = "lospec"))]
+ fn lospec_slug(&self) -> Option<&str> {
+ None
+ }
}
#[derive(Parser, Debug)]
@@ -135,41 +321,56 @@ pub struct ProcessArgs {
// --- Output Size ---
/// Target output width (default: same as input)
- #[arg(long)]
+ #[arg(long, hide_short_help = true)]
pub target_width: Option,
/// Target output height (default: same as input)
- #[arg(long)]
+ #[arg(long, hide_short_help = true)]
pub target_height: Option,
+ /// Output encoding (also sets the derived output extension)
+ #[arg(long, value_enum, default_value_t, hide_short_help = true)]
+ pub output_format: crate::image_util::io::OutputFormat,
+
+ /// Also write a diagnostic overlay PNG: the source dimmed, blocks
+ /// tinted red by how contested their color vote was — a wrong pitch or
+ /// phase lights up instantly
+ #[arg(long, hide_short_help = true)]
+ pub debug_overlay: Option,
+
/// Overwrite output file if it exists
- #[arg(long)]
+ #[arg(long, overrides_with = "no_overwrite")]
pub overwrite: bool,
+ /// Never overwrite outputs (overrides a config file that enables it)
+ #[arg(long, overrides_with = "overwrite", hide_short_help = true)]
+ pub no_overwrite: bool,
+
/// Pipeline options
#[command(flatten)]
pub pipeline: PipelineFlags,
}
impl ProcessArgs {
- /// Compute the output path. Defaults to ` {
+ overwrite_tristate(self.overwrite, self.no_overwrite)
+ }
+
+ /// Compute the output path. Defaults to `` —
+ /// the OUTPUT format's extension, never the input's.
pub fn output_path(&self) -> PathBuf {
if let Some(ref out) = self.output {
out.clone()
} else {
- let stem = self
- .input
- .file_stem()
- .unwrap_or_default()
- .to_string_lossy();
- let ext = self
- .input
- .extension()
- .unwrap_or_default()
- .to_string_lossy();
- let ext = if ext.is_empty() { "png" } else { &ext };
- self.input
- .with_file_name(format!("{}_normalized.{}", stem, ext))
+ crate::paths::derive_output_path(
+ &self.input,
+ None,
+ &crate::paths::OutputNaming {
+ suffix: "_normalized",
+ extension: self.output_format.extension(),
+ },
+ )
}
}
}
@@ -183,14 +384,38 @@ pub struct BatchArgs {
pub output: PathBuf,
/// Overwrite output files if they exist
- #[arg(long)]
+ #[arg(long, overrides_with = "no_overwrite")]
pub overwrite: bool,
+ /// Never overwrite outputs (overrides a config file that enables it)
+ #[arg(long, overrides_with = "overwrite", hide_short_help = true)]
+ pub no_overwrite: bool,
+
+ /// Suffix appended to output stems (pass '' for none) [default: _normalized]
+ #[arg(long)]
+ pub suffix: Option,
+
+ /// Recreate the inputs' relative directory structure under the output
+ /// directory (avoids name collisions with recursive globs)
+ #[arg(long)]
+ pub preserve_dirs: bool,
+
+ /// Output encoding (also sets the output extension)
+ #[arg(long, value_enum, default_value_t)]
+ pub output_format: crate::image_util::io::OutputFormat,
+
/// Pipeline options
#[command(flatten)]
pub pipeline: PipelineFlags,
}
+impl BatchArgs {
+ /// Tri-state from the --overwrite / --no-overwrite pair.
+ pub fn overwrite_opt(&self) -> Option {
+ overwrite_tristate(self.overwrite, self.no_overwrite)
+ }
+}
+
#[derive(Parser, Debug)]
pub struct SheetArgs {
/// Input sprite sheet image
@@ -216,9 +441,13 @@ pub struct SheetArgs {
pub margin: u32,
/// Overwrite output file if it exists
- #[arg(long)]
+ #[arg(long, overrides_with = "no_overwrite")]
pub overwrite: bool,
+ /// Never overwrite outputs (overrides a config file that enables it)
+ #[arg(long, overrides_with = "overwrite", hide_short_help = true)]
+ pub no_overwrite: bool,
+
// --- Auto-split options ---
/// Fraction of background pixels to classify a row/column as a separator (0.0-1.0, default: 0.90)
#[arg(long)]
@@ -246,24 +475,18 @@ pub struct SheetArgs {
}
impl SheetArgs {
- /// Compute the output path. Defaults to ` {
+ overwrite_tristate(self.overwrite, self.no_overwrite)
+ }
+
+ /// Compute the output path. Defaults to `,
+
+ /// Overwrite the output file if it exists
+ #[arg(long)]
+ pub overwrite: bool,
+
+ /// Bypass the local cache and re-fetch from Lospec
+ #[arg(long)]
+ pub refresh: bool,
}
#[derive(Parser, Debug)]
@@ -308,9 +539,49 @@ pub struct PaletteExtractArgs {
/// Save palette as .hex file
#[arg(long, short)]
pub output: Option,
+
+ /// Overwrite the output file if it exists
+ #[arg(long)]
+ pub overwrite: bool,
+}
+
+fn overwrite_tristate(yes: bool, no: bool) -> Option {
+ if yes {
+ Some(true)
+ } else if no {
+ Some(false)
+ } else {
+ None
+ }
+}
+
+/// Validate a built-in palette name at parse time.
+fn parse_palette_name(s: &str) -> std::result::Result {
+ let slug = s.to_lowercase();
+ if crate::color::palettes::ALL_PALETTES
+ .iter()
+ .any(|p| p.slug == slug)
+ {
+ Ok(slug)
+ } else {
+ let available: Vec<&str> = crate::color::palettes::ALL_PALETTES
+ .iter()
+ .map(|p| p.slug)
+ .collect();
+ Err(format!(
+ "unknown palette '{}'. Available: {}",
+ s,
+ available.join(", ")
+ ))
+ }
+}
+
+/// Validate a hex color at parse time.
+fn parse_hex_color_arg(s: &str) -> std::result::Result<[u8; 3], String> {
+ crate::config::parse_hex_color(s)
}
-fn parse_phase(s: &str) -> Result<(u32, u32), String> {
+fn parse_phase(s: &str) -> std::result::Result<(u32, u32), String> {
let parts: Vec<&str> = s.split(',').collect();
if parts.len() != 2 {
return Err("Phase must be in format 'X,Y' (e.g., '1,2')".to_string());
diff --git a/src/color/kmeans.rs b/src/color/kmeans.rs
index c8864a7..d945ccc 100644
--- a/src/color/kmeans.rs
+++ b/src/color/kmeans.rs
@@ -1,113 +1,234 @@
+//! Weighted, seeded k-means clustering in OKLAB space.
+//!
+//! Points are unique colors weighted by their pixel counts — clustering the
+//! histogram instead of raw pixels is exact, orders of magnitude faster on
+//! post-snap images (a few hundred uniques), and keeps rare-but-structural
+//! colors (1px outlines) from being dropped by subsampling. All randomness
+//! comes from a caller-provided seed via ChaCha8, so identical inputs
+//! produce identical palettes on every run and platform.
+
use palette::Oklab;
-use rand::seq::SliceRandom;
use rand::Rng;
+use rand::SeedableRng;
+use rand_chacha::ChaCha8Rng;
use crate::color::oklab::oklab_distance_sq;
-/// Run k-means++ clustering in OKLAB space.
-///
-/// Returns a Vec of `k` centroid colors.
+/// Configuration for a weighted k-means run.
+#[derive(Debug, Clone)]
+pub struct KmeansConfig {
+ /// Total number of centroids, INCLUDING pinned ones.
+ pub k: usize,
+ /// Maximum Lloyd's iterations.
+ pub max_iterations: usize,
+ /// RNG seed; the only source of randomness.
+ pub seed: u64,
+}
+
+/// Result of a weighted k-means run.
+#[derive(Debug, Clone)]
+pub struct KmeansResult {
+ /// Centroids; pinned ones occupy indices `0..pinned.len()` unchanged.
+ pub centroids: Vec,
+ /// Per input point: index into `centroids`.
+ pub assignments: Vec,
+}
+
+/// Weighted k-means++ / Lloyd's over unique colors.
///
-/// Uses k-means++ initialization for better starting positions,
-/// then runs Lloyd's algorithm until convergence.
-pub fn kmeans_oklab(colors: &[Oklab], k: usize, max_iterations: usize) -> Vec {
- if colors.is_empty() || k == 0 {
- return Vec::new();
+/// - Init: k-means++ with a running min-distance array (O(n·k)), sampling
+/// probability proportional to `weight · min_dist²`.
+/// - `pinned` centroids participate in assignment and in the init distance
+/// field but are never moved by the update step (dither-pair colors).
+/// - Empty clusters are reseeded at the point with the largest weighted
+/// distance to its centroid, so `k` requested colors means `k` effective
+/// colors whenever the input has that many distinct points.
+pub fn kmeans_weighted(
+ points: &[Oklab],
+ weights: &[u32],
+ pinned: &[Oklab],
+ config: &KmeansConfig,
+) -> KmeansResult {
+ assert_eq!(points.len(), weights.len());
+ if points.is_empty() || config.k == 0 {
+ return KmeansResult {
+ centroids: pinned.to_vec(),
+ assignments: Vec::new(),
+ };
}
- let k = k.min(colors.len());
- // K-means++ initialization
- let mut rng = rand::thread_rng();
- let mut centroids = kmeans_plus_plus_init(colors, k, &mut rng);
+ let k = config
+ .k
+ .clamp(pinned.len().min(config.k), points.len().max(pinned.len()));
+ let n_pinned = pinned.len().min(k);
+ let mut rng = ChaCha8Rng::seed_from_u64(config.seed);
- let mut assignments = vec![0usize; colors.len()];
+ // ---- k-means++ init with running min-distance array ----
+ let mut centroids: Vec = pinned[..n_pinned].to_vec();
+ let mut min_dist: Vec = if centroids.is_empty() {
+ vec![f32::MAX; points.len()]
+ } else {
+ points
+ .iter()
+ .map(|p| {
+ centroids
+ .iter()
+ .map(|c| oklab_distance_sq(*p, *c))
+ .fold(f32::MAX, f32::min)
+ })
+ .collect()
+ };
- for _iter in 0..max_iterations {
- // Assignment step: assign each point to nearest centroid
+ if centroids.is_empty() {
+ // First centroid: the heaviest point (deterministic, and a sensible
+ // anchor for pixel art where the dominant color matters most).
+ let first = weights
+ .iter()
+ .enumerate()
+ .max_by(|a, b| a.1.cmp(b.1).then(b.0.cmp(&a.0)))
+ .map(|(i, _)| i)
+ .unwrap();
+ centroids.push(points[first]);
+ for (i, p) in points.iter().enumerate() {
+ min_dist[i] = oklab_distance_sq(*p, points[first]);
+ }
+ }
+
+ while centroids.len() < k {
+ let total: f64 = points
+ .iter()
+ .enumerate()
+ .map(|(i, _)| weights[i] as f64 * min_dist[i] as f64)
+ .sum();
+ if total <= 0.0 {
+ break; // All points coincide with existing centroids
+ }
+ let threshold = rng.random::() * total;
+ let mut cumulative = 0.0f64;
+ let mut chosen = points.len() - 1;
+ for i in 0..points.len() {
+ cumulative += weights[i] as f64 * min_dist[i] as f64;
+ if cumulative >= threshold {
+ chosen = i;
+ break;
+ }
+ }
+ let c = points[chosen];
+ centroids.push(c);
+ for (i, p) in points.iter().enumerate() {
+ let d = oklab_distance_sq(*p, c);
+ if d < min_dist[i] {
+ min_dist[i] = d;
+ }
+ }
+ }
+ let k = centroids.len();
+
+ // ---- Lloyd's iterations ----
+ let mut assignments = vec![0usize; points.len()];
+ for _iter in 0..config.max_iterations {
+ // Assignment
let mut changed = false;
- for (i, color) in colors.iter().enumerate() {
- let nearest = nearest_centroid(*color, ¢roids);
+ for (i, p) in points.iter().enumerate() {
+ let nearest = nearest_centroid(*p, ¢roids);
if nearest != assignments[i] {
assignments[i] = nearest;
changed = true;
}
}
- if !changed {
- break; // Converged
- }
-
- // Update step: recompute centroids as mean of assigned points
- let mut sums_l = vec![0.0f64; k];
- let mut sums_a = vec![0.0f64; k];
- let mut sums_b = vec![0.0f64; k];
- let mut counts = vec![0u32; k];
-
- for (i, color) in colors.iter().enumerate() {
+ // Update (free centroids only)
+ let mut sums = vec![(0.0f64, 0.0f64, 0.0f64, 0.0f64); k];
+ for (i, p) in points.iter().enumerate() {
let c = assignments[i];
- sums_l[c] += color.l as f64;
- sums_a[c] += color.a as f64;
- sums_b[c] += color.b as f64;
- counts[c] += 1;
+ let w = weights[i] as f64;
+ sums[c].0 += p.l as f64 * w;
+ sums[c].1 += p.a as f64 * w;
+ sums[c].2 += p.b as f64 * w;
+ sums[c].3 += w;
}
- for c in 0..k {
- if counts[c] > 0 {
- let n = counts[c] as f64;
+ let mut reseeded = false;
+ for c in n_pinned..k {
+ if sums[c].3 > 0.0 {
+ let w = sums[c].3;
centroids[c] = Oklab::new(
- (sums_l[c] / n) as f32,
- (sums_a[c] / n) as f32,
- (sums_b[c] / n) as f32,
+ (sums[c].0 / w) as f32,
+ (sums[c].1 / w) as f32,
+ (sums[c].2 / w) as f32,
);
+ } else {
+ // Empty cluster: reseed at the point farthest (weighted)
+ // from its current centroid.
+ let far = points
+ .iter()
+ .enumerate()
+ .max_by(|(i, p), (j, q)| {
+ let di = weights[*i] as f64
+ * oklab_distance_sq(**p, centroids[assignments[*i]]) as f64;
+ let dj = weights[*j] as f64
+ * oklab_distance_sq(**q, centroids[assignments[*j]]) as f64;
+ di.total_cmp(&dj).then(j.cmp(i))
+ })
+ .map(|(i, _)| i)
+ .unwrap();
+ centroids[c] = points[far];
+ reseeded = true;
}
}
+
+ if !changed && !reseeded {
+ break; // Converged
+ }
}
- centroids
+ KmeansResult {
+ centroids,
+ assignments,
+ }
}
-/// K-means++ initialization: choose k initial centroids with probability
-/// proportional to squared distance from nearest existing centroid.
-fn kmeans_plus_plus_init(colors: &[Oklab], k: usize, rng: &mut impl Rng) -> Vec {
- let mut centroids = Vec::with_capacity(k);
-
- // First centroid: random point
- let first = colors.choose(rng).copied().unwrap();
- centroids.push(first);
-
- // Subsequent centroids: weighted by distance to nearest existing centroid
- for _ in 1..k {
- let weights: Vec = colors
- .iter()
- .map(|c| {
- centroids
- .iter()
- .map(|cent| oklab_distance_sq(*c, *cent))
- .fold(f32::MAX, f32::min)
- })
- .collect();
-
- let total: f32 = weights.iter().sum();
- if total <= 0.0 {
- // All remaining points are at existing centroids
- break;
- }
-
- // Weighted random selection
- let threshold = rng.gen::() * total;
- let mut cumulative = 0.0f32;
- let mut chosen = colors.len() - 1;
- for (i, &w) in weights.iter().enumerate() {
- cumulative += w;
- if cumulative >= threshold {
- chosen = i;
- break;
- }
+/// Per cluster, the index of the member minimizing the weighted sum of
+/// squared distances to the other members (tie-break: heavier point, then
+/// lower index). `None` for clusters with no members.
+pub fn weighted_medoids(
+ points: &[Oklab],
+ weights: &[u32],
+ assignments: &[usize],
+ k: usize,
+) -> Vec> {
+ let mut members: Vec> = vec![Vec::new(); k];
+ for (i, &c) in assignments.iter().enumerate() {
+ if c < k {
+ members[c].push(i);
}
- centroids.push(colors[chosen]);
}
- centroids
+ members
+ .iter()
+ .map(|cluster| {
+ if cluster.is_empty() {
+ return None;
+ }
+ cluster
+ .iter()
+ .map(|&i| {
+ let cost: f64 = cluster
+ .iter()
+ .map(|&j| {
+ weights[j] as f64 * oklab_distance_sq(points[i], points[j]) as f64
+ })
+ .sum();
+ (i, cost)
+ })
+ .min_by(|a, b| {
+ a.1.total_cmp(&b.1)
+ .then(weights[b.0].cmp(&weights[a.0]))
+ .then(a.0.cmp(&b.0))
+ })
+ .map(|(i, _)| i)
+ })
+ .collect()
}
/// Find the index of the nearest centroid to a given color.
@@ -116,76 +237,124 @@ pub fn nearest_centroid(color: Oklab, centroids: &[Oklab]) -> usize {
.iter()
.enumerate()
.min_by(|(_, a), (_, b)| {
- oklab_distance_sq(color, **a)
- .partial_cmp(&oklab_distance_sq(color, **b))
- .unwrap()
+ oklab_distance_sq(color, **a).total_cmp(&oklab_distance_sq(color, **b))
})
.map(|(i, _)| i)
.unwrap_or(0)
}
-/// Subsample colors for faster k-means on large images.
-/// Takes at most `max_samples` random samples from the input.
-pub fn subsample(colors: &[Oklab], max_samples: usize) -> Vec {
- if colors.len() <= max_samples {
- return colors.to_vec();
- }
- let mut rng = rand::thread_rng();
- let mut indices: Vec = (0..colors.len()).collect();
- indices.shuffle(&mut rng);
- indices.truncate(max_samples);
- indices.iter().map(|&i| colors[i]).collect()
-}
-
#[cfg(test)]
mod tests {
use super::*;
- #[test]
- fn test_kmeans_two_clusters() {
- // Create two distinct clusters: around (0.3, 0, 0) and (0.7, 0, 0)
- let mut colors = Vec::new();
- for _ in 0..50 {
- colors.push(Oklab::new(0.3, 0.0, 0.0));
- }
- for _ in 0..50 {
- colors.push(Oklab::new(0.7, 0.0, 0.0));
+ fn config(k: usize) -> KmeansConfig {
+ KmeansConfig {
+ k,
+ max_iterations: 50,
+ seed: 0,
}
+ }
- let centroids = kmeans_oklab(&colors, 2, 50);
- assert_eq!(centroids.len(), 2);
+ #[test]
+ fn test_kmeans_two_clusters() {
+ let points = vec![Oklab::new(0.3, 0.0, 0.0), Oklab::new(0.7, 0.0, 0.0)];
+ let weights = vec![50, 50];
+ let result = kmeans_weighted(&points, &weights, &[], &config(2));
+ assert_eq!(result.centroids.len(), 2);
- // Centroids should be near 0.3 and 0.7
- let mut ls: Vec = centroids.iter().map(|c| c.l).collect();
- ls.sort_by(|a, b| a.partial_cmp(b).unwrap());
+ let mut ls: Vec = result.centroids.iter().map(|c| c.l).collect();
+ ls.sort_by(f32::total_cmp);
assert!((ls[0] - 0.3).abs() < 0.05);
assert!((ls[1] - 0.7).abs() < 0.05);
}
#[test]
- fn test_kmeans_single_color() {
- let colors = vec![Oklab::new(0.5, 0.1, -0.1); 100];
- let centroids = kmeans_oklab(&colors, 3, 50);
- // Should still produce centroids (some may be duplicates)
- assert!(!centroids.is_empty());
+ fn test_same_seed_identical_output() {
+ let points: Vec = (0..200)
+ .map(|i| Oklab::new(i as f32 / 200.0, (i % 7) as f32 * 0.01, 0.0))
+ .collect();
+ let weights: Vec