@jjlmoya/utils-games-development 1.54.0 → 1.56.0

package/src/tool/pixelArtPaletteSwapper/i18n/zh.ts

@@ -0,0 +1,225 @@
+import type { ToolLocaleContent } from '../../../types';
+import type { PixelArtPaletteSwapperUI } from '../ui';
+
+export const content: ToolLocaleContent<PixelArtPaletteSwapperUI> = {
+  slug: 'pixel-art-palette-swapper',
+  title: '像素艺术调色板调换工具',
+  description: '在浏览器中将精灵图和精灵图集快速转换为复古主机调色板或自定义 Hex 颜色。',
+  ui: {
+    uploadTitle: '拖放精灵图或精灵图集',
+    uploadHint: 'PNG、JPEG 或 WebP 文件均在本地处理',
+    chooseImage: '选择图片',
+    replaceImage: '替换图片',
+    paletteTitle: '选择调色板',
+    gameBoyPalette: 'Game Boy',
+    nesPalette: 'NES 风格',
+    pico8Palette: 'PICO-8',
+    commodore64Palette: 'Commodore 64',
+    dawnBringerPalette: 'DawnBringer 16',
+    customPalette: '自定义颜色',
+    customPaletteHint: '使用逗号、空格或换行分隔 Hex 颜色代码。',
+    applyCustomPalette: '应用调色板',
+    resetCustomPalette: '重置',
+    sourcePreview: '原图',
+    resultPreview: '转换结果',
+    waitingForImage: '等待加载图片',
+    uploadToPreview: '上传图片以预览效果',
+    resultEmpty: '原图与调色板转换后的效果将并排显示。',
+    downloadPng: '下载 PNG',
+    downloadDisabled: '请先上传图片以启用导出。',
+    colorCount: '原图颜色数',
+    mappedCount: '已用颜色数',
+    imageSize: '图片尺寸',
+    paletteCount: '调色板颜色数',
+    preserveAlpha: '保留透明度',
+    zoomLabel: '缩放',
+    processing: '正在映射像素',
+    invalidPalette: '请至少添加一个有效的 Hex 颜色代码',
+    invalidImage: '请选择 PNG、JPEG 或 WebP 格式图片',
+    readyStatus: '就绪',
+    dropActive: '松开即可加载',
+    mappedSummary: '已将 {source} 种原图颜色映射至 {mapped} 种调色板颜色',
+  },
+  seo: [
+    {
+      type: 'title',
+      level: 2,
+      text: '将全彩像素图转换为经典的复古主机配色',
+    },
+    {
+      type: 'paragraph',
+      html: '限制色彩数量能赋予像素艺术独特的复古风格。本工具支持转换为 Game Boy、NES、PICO-8 等经典主机的调色板。',
+    },
+    {
+      type: 'title',
+      level: 2,
+      text: '颜色映射计算原理',
+    },
+    {
+      type: 'paragraph',
+      html: '工具会计算每个像素 RGB 值的距离，并将其替换为目标调色板中最接近的颜色，同时完好保留透明通道。',
+    },
+    {
+      type: 'comparative',
+      columns: 2,
+      items: [
+        {
+          title: '调色板限制',
+          description: '将原有颜色替换为最接近的色块。',
+          points: [
+            '适合像素角色、图标及图块集',
+            '保持原始尺寸与像素位置不变',
+            '便于精确掌控色彩预算',
+          ],
+        },
+        {
+          title: '调色板调换（Palette Swapping）',
+          description: '快速生成不同配色的角色或场景。',
+          points: [
+            '常用于换装、变色或状态变化',
+            '支持自定义 Hex 列表导入',
+            '可直接下载 PNG 导入引擎',
+          ],
+        },
+      ],
+    },
+    {
+      type: 'title',
+      level: 2,
+      text: '复古调色板对比',
+    },
+    {
+      type: 'table',
+      headers: ['调色板', '颜色数', '适用场景', '注意事项'],
+      rows: [
+        ['Game Boy', '4', '黑白掌机复古风格', '对比度较低时细节易混淆'],
+        ['NES 风格', '16', '经典街机与平台动作游戏', '高饱和度颜色需注意搭配'],
+        ['PICO-8', '16', '现代鲜艳像素风格', '注意控制高饱和色彩的对比'],
+        ['Commodore 64', '16', '复古电脑端艺术风格', '清晰的轮廓有助于提升识别度'],
+        ['DawnBringer 16', '16', '通用性极高的手绘调色板', '需要明确的光影方向'],
+      ],
+    },
+    {
+      type: 'title',
+      level: 2,
+      text: '精灵图集工作流建议',
+    },
+    {
+      type: 'paragraph',
+      html: '上传导出好的精灵图集，利用放大功能仔细检查面部细节和轮廓线是否保持清晰。',
+    },
+    {
+      type: 'tip',
+      title: '控制色彩数量',
+      html: '将颜色控制在 4 到 16 色之间通常能获得最干练清晰的效果。',
+    },
+    {
+      type: 'title',
+      level: 2,
+      text: '导出前检查清单',
+    },
+    {
+      type: 'diagnostic',
+      variant: 'info',
+      title: '导入游戏前的准备',
+      html: '在 100% 比例下检查画面，确保透明边缘干净无杂色。',
+    },
+    {
+      type: 'glossary',
+      items: [
+        {
+          term: '色彩量化（Quantization）',
+          definition: '将大量颜色缩减为较小固定颜色集合的过程。',
+        },
+        {
+          term: '色彩阶梯（Ramp）',
+          definition: '用于表现明暗过渡和材质体感的一组同系颜色。',
+        },
+        {
+          term: '索引调色板',
+          definition: '像素通过引用色表序号来确定颜色的存储形式。',
+        },
+      ],
+    },
+  ],
+  faq: [
+    {
+      question: '我的图片会被上传到服务器吗？',
+      answer: '不会。所有图像处理均在您的浏览器本地进行。',
+    },
+    {
+      question: '支持使用我自己的调色板吗？',
+      answer: '支持。在自定义颜色框中输入 Hex 代码并点击应用调色板即可。',
+    },
+  ],
+  howTo: [
+    {
+      name: '加载图片',
+      text: '拖放 PNG、JPEG 或 WebP 图片到工作区。',
+    },
+    {
+      name: '选择调色板',
+      text: '选择预设或输入自定义 Hex 代码。',
+    },
+    {
+      name: '导出结果',
+      text: '下载转换后的 PNG 格式图片。',
+    },
+  ],
+  schemas: [
+    {
+      '@context': 'https://schema.org',
+      '@type': 'SoftwareApplication',
+      name: '像素艺术调色板调换工具',
+      applicationCategory: 'DesignApplication',
+      operatingSystem: 'Any',
+      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      mainEntity: [
+        {
+          '@type': 'Question',
+          name: '我的图片会被上传到服务器吗？',
+          acceptedAnswer: {
+            '@type': 'Answer',
+            text: '不会。所有图像处理均在您的浏览器本地进行。',
+          },
+        },
+        {
+          '@type': 'Question',
+          name: '支持使用我自己的调色板吗？',
+          acceptedAnswer: {
+            '@type': 'Answer',
+            text: '支持。在自定义颜色框中输入 Hex 代码并点击应用调色板即可。',
+          },
+        },
+      ],
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'HowTo',
+      name: '如何将像素图转换至复古调色板',
+      step: [
+        { '@type': 'HowToStep', name: '加载图片', text: '拖放图片到工作区。' },
+        { '@type': 'HowToStep', name: '选择调色板', text: '选择预设或输入自定义 Hex 代码。' },
+        { '@type': 'HowToStep', name: '导出结果', text: '下载转换后的 PNG 格式图片。' },
+      ],
+    },
+  ],
+  bibliography: [
+    {
+      name: 'MDN Canvas API',
+      url: 'https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API',
+    },
+    {
+      name: 'Lospec Palette List',
+      url: 'https://lospec.com/palette-list',
+    },
+    {
+      name: 'W3C Portable Network Graphics Specification',
+      url: 'https://www.w3.org/TR/png-3/',
+    },
+  ],
+};

package/src/tool/pixelArtPaletteSwapper/index.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from '../../types';
+import { pixelArtPaletteSwapper } from './entry';
+
+export * from './entry';
+export * from './logic';
+
+export const PIXEL_ART_PALETTE_SWAPPER_TOOL: ToolDefinition = {
+  entry: pixelArtPaletteSwapper,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/pixelArtPaletteSwapper/logic.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PRESET_PALETTES,
+  findNearestColor,
+  hexToRgb,
+  parsePaletteInput,
+  quantizeImageData,
+  rgbToHex,
+} from './logic';
+
+describe('pixel art palette swapper logic', () => {
+  it('parses short and full hex colors into normalized values', () => {
+    expect(hexToRgb('#0f8')).toEqual({ r: 0, g: 255, b: 136 });
+    expect(rgbToHex({ r: 18, g: 52, b: 86 })).toBe('#123456');
+  });
+
+  it('removes invalid and duplicate custom colors', () => {
+    expect(parsePaletteInput('#000, #ffffff, nope, #000000')).toEqual([
+      { r: 0, g: 0, b: 0, hex: '#000000' },
+      { r: 255, g: 255, b: 255, hex: '#ffffff' },
+    ]);
+  });
+
+  it('chooses the closest palette color in RGB space', () => {
+    const palette = parsePaletteInput('#000000 #ffffff');
+    expect(findNearestColor({ r: 220, g: 220, b: 220 }, palette)?.hex).toBe('#ffffff');
+    expect(findNearestColor({ r: 30, g: 30, b: 30 }, palette)?.hex).toBe('#000000');
+  });
+
+  it('maps opaque pixels while preserving transparent pixels and alpha', () => {
+    const source = new Uint8ClampedArray([
+      240, 20, 20, 255,
+      10, 10, 10, 128,
+      255, 255, 255, 0,
+    ]);
+    const result = quantizeImageData(source, PRESET_PALETTES.pico8);
+    expect(Array.from(result.data.slice(0, 4))).toEqual([255, 0, 77, 255]);
+    expect(result.data[7]).toBe(128);
+    expect(Array.from(result.data.slice(8, 12))).toEqual([255, 255, 255, 0]);
+    expect(result.sourceColors).toBe(2);
+    expect(result.mappedColors).toBe(2);
+  });
+});

package/src/tool/pixelArtPaletteSwapper/logic.ts

@@ -0,0 +1,171 @@
+export interface RGBColor {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface PaletteColor extends RGBColor {
+  hex: string;
+}
+
+export interface QuantizationResult {
+  data: Uint8ClampedArray;
+  sourceColors: number;
+  mappedColors: number;
+}
+
+export const PRESET_PALETTES: Record<string, PaletteColor[]> = {
+  gameBoy: ['#0f380f', '#306230', '#8bac0f', '#9bbc0f'].map(createPresetPaletteColor),
+  nes: [
+    '#000000', '#fcfcfc', '#f8f8f8', '#b8b8b8', '#7c7c7c', '#a80000', '#e45c10', '#f8b800',
+    '#f8d878', '#00a800', '#58d854', '#b8f8b8', '#0058f8', '#00a8e8', '#3cbcfc', '#a4e4fc',
+  ].map(createPresetPaletteColor),
+  pico8: [
+    '#000000', '#1d2b53', '#7e2553', '#008751', '#ab5236', '#5f574f', '#c2c3c7', '#fff1e8',
+    '#ff004d', '#ffa300', '#ffec27', '#00e436', '#29adff', '#83769c', '#ff77a8', '#ffccaa',
+  ].map(createPresetPaletteColor),
+  commodore64: [
+    '#000000', '#ffffff', '#813338', '#75cec8', '#8e3c97', '#56ac4d', '#2e2c9b', '#edf171',
+    '#8e5029', '#553800', '#c46c71', '#4a4a4a', '#7b7b7b', '#a9ff9f', '#706deb', '#b2b2b2',
+  ].map(createPresetPaletteColor),
+  dawnBringer16: [
+    '#140c1c', '#442434', '#30346d', '#4e4a4e', '#854c30', '#346524', '#d04648', '#757161',
+    '#597dce', '#d27d2c', '#8595a1', '#6daa2c', '#d2aa99', '#6dc2ca', '#dad45e', '#deeed6',
+  ].map(createPresetPaletteColor),
+};
+
+export function createPaletteColor(hex: string): PaletteColor {
+  const rgb = hexToRgb(hex);
+  if (!rgb) {
+    throw new Error(`Invalid color: ${hex}`);
+  }
+
+  return { ...rgb, hex: rgbToHex(rgb) };
+}
+
+export function hexToRgb(value: string): RGBColor | null {
+  const normalized = value.trim().replace(/^#/, '');
+  const expanded = normalized.length === 3
+    ? normalized.split('').map((channel) => `${channel}${channel}`).join('')
+    : normalized;
+
+  if (!/^[0-9a-f]{6}$/i.test(expanded)) {
+    return null;
+  }
+
+  return {
+    r: Number.parseInt(expanded.slice(0, 2), 16),
+    g: Number.parseInt(expanded.slice(2, 4), 16),
+    b: Number.parseInt(expanded.slice(4, 6), 16),
+  };
+}
+
+export function rgbToHex(color: RGBColor): string {
+  return `#${[color.r, color.g, color.b]
+    .map((channel) => Math.max(0, Math.min(255, Math.round(channel))).toString(16).padStart(2, '0'))
+    .join('')}`;
+}
+
+export function parsePaletteInput(value: string): PaletteColor[] {
+  const colors = value
+    .split(/[\s,;]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+  const seen = new Set<string>();
+  const palette: PaletteColor[] = [];
+
+  for (const color of colors) {
+    const parsed = hexToRgb(color);
+    if (!parsed) {
+      continue;
+    }
+    const hex = rgbToHex(parsed);
+    if (!seen.has(hex)) {
+      seen.add(hex);
+      palette.push({ ...parsed, hex });
+    }
+  }
+
+  return palette;
+}
+
+export function findNearestColor(source: RGBColor, palette: PaletteColor[]): PaletteColor | null {
+  if (palette.length === 0) {
+    return null;
+  }
+
+  let nearest = palette[0];
+  let distance = colorDistanceSquared(source, nearest);
+
+  for (let index = 1; index < palette.length; index += 1) {
+    const candidate = palette[index];
+    const candidateDistance = colorDistanceSquared(source, candidate);
+    if (candidateDistance < distance) {
+      nearest = candidate;
+      distance = candidateDistance;
+    }
+  }
+
+  return nearest;
+}
+
+export function colorDistanceSquared(first: RGBColor, second: RGBColor): number {
+  const red = first.r - second.r;
+  const green = first.g - second.g;
+  const blue = first.b - second.b;
+  return red * red + green * green + blue * blue;
+}
+
+interface QuantizePixelContext {
+  data: Uint8ClampedArray;
+  index: number;
+  palette: PaletteColor[];
+  preserveTransparency: boolean;
+  sourceColors: Set<string>;
+  mappedColors: Set<string>;
+}
+
+function processPixel(ctx: QuantizePixelContext): void {
+  const { data, index, palette, preserveTransparency, sourceColors, mappedColors } = ctx;
+  const alpha = data[index + 3];
+  if (alpha === 0 && preserveTransparency) return;
+
+  const sourceColor = { r: data[index], g: data[index + 1], b: data[index + 2] };
+  const mapped = findNearestColor(sourceColor, palette);
+  if (!mapped) return;
+
+  sourceColors.add(rgbToHex(sourceColor));
+  mappedColors.add(mapped.hex);
+  data[index] = mapped.r;
+  data[index + 1] = mapped.g;
+  data[index + 2] = mapped.b;
+  if (!preserveTransparency) data[index + 3] = 255;
+}
+
+export function quantizeImageData(
+  source: Uint8ClampedArray,
+  palette: PaletteColor[],
+  preserveTransparency = true,
+): QuantizationResult {
+  const data = new Uint8ClampedArray(source);
+  const sourceColors = new Set<string>();
+  const mappedColors = new Set<string>();
+
+  if (palette.length === 0) {
+    return { data, sourceColors: 0, mappedColors: 0 };
+  }
+
+  for (let index = 0; index < data.length; index += 4) {
+    processPixel({ data, index, palette, preserveTransparency, sourceColors, mappedColors });
+  }
+
+  return { data, sourceColors: sourceColors.size, mappedColors: mappedColors.size };
+}
+
+function createPresetPaletteColor(hex: string): PaletteColor {
+  const rgb = hexToRgb(hex);
+  if (!rgb) {
+    throw new Error(`Invalid color: ${hex}`);
+  }
+  return { ...rgb, hex: rgbToHex(rgb) };
+}