spriteforge 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. spriteforge/__init__.py +1 -0
  2. spriteforge/__main__.py +3 -0
  3. spriteforge/agents/__init__.py +0 -0
  4. spriteforge/agents/assets.py +109 -0
  5. spriteforge/agents/cancellation.py +12 -0
  6. spriteforge/agents/director.py +50 -0
  7. spriteforge/agents/models.py +63 -0
  8. spriteforge/agents/roles/art-director.md +15 -0
  9. spriteforge/agents/roles/art-reviewer.md +14 -0
  10. spriteforge/agents/roles/director.md +14 -0
  11. spriteforge/agents/roles/game-designer.md +15 -0
  12. spriteforge/agents/roles/level-tile-designer.md +16 -0
  13. spriteforge/agents/roles/librarian.md +13 -0
  14. spriteforge/agents/roles/menu-designer.md +15 -0
  15. spriteforge/agents/roles/pixel-artist.md +14 -0
  16. spriteforge/agents/roles/programmer.md +14 -0
  17. spriteforge/agents/roles/qa-playtester.md +13 -0
  18. spriteforge/agents/roles/sound-director.md +14 -0
  19. spriteforge/agents/roles.py +39 -0
  20. spriteforge/agents/router.py +233 -0
  21. spriteforge/agents/router_eval.py +145 -0
  22. spriteforge/agents/routing_state.py +133 -0
  23. spriteforge/agents/runtime.py +430 -0
  24. spriteforge/agents/workflow.py +389 -0
  25. spriteforge/app/__init__.py +0 -0
  26. spriteforge/app/agents_view.py +248 -0
  27. spriteforge/app/chat.py +114 -0
  28. spriteforge/app/extensions.py +115 -0
  29. spriteforge/app/index.html +279 -0
  30. spriteforge/app/local_only.py +49 -0
  31. spriteforge/app/server.py +358 -0
  32. spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
  33. spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
  34. spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
  35. spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
  36. spriteforge/app/static/index.html +13 -0
  37. spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
  38. spriteforge/app/studio.py +278 -0
  39. spriteforge/app/workers.py +73 -0
  40. spriteforge/cli.py +241 -0
  41. spriteforge/config.py +193 -0
  42. spriteforge/config.yaml +157 -0
  43. spriteforge/core/__init__.py +0 -0
  44. spriteforge/core/acting.py +16 -0
  45. spriteforge/core/cost.py +236 -0
  46. spriteforge/core/credentials.py +24 -0
  47. spriteforge/core/demo.py +79 -0
  48. spriteforge/core/forms.py +20 -0
  49. spriteforge/core/gates.py +175 -0
  50. spriteforge/core/security.py +42 -0
  51. spriteforge/core/state.py +222 -0
  52. spriteforge/core/team.py +15 -0
  53. spriteforge/core/usage.py +68 -0
  54. spriteforge/game/__init__.py +0 -0
  55. spriteforge/game/actors.py +377 -0
  56. spriteforge/game/agent_tools.py +178 -0
  57. spriteforge/game/art.py +2097 -0
  58. spriteforge/game/art_checks.py +190 -0
  59. spriteforge/game/art_review.py +518 -0
  60. spriteforge/game/build.py +134 -0
  61. spriteforge/game/bundle.py +1178 -0
  62. spriteforge/game/cli.py +119 -0
  63. spriteforge/game/codegen.py +433 -0
  64. spriteforge/game/codeinfo.py +154 -0
  65. spriteforge/game/dbsource.py +137 -0
  66. spriteforge/game/design.py +342 -0
  67. spriteforge/game/export.py +62 -0
  68. spriteforge/game/gamedb.py +191 -0
  69. spriteforge/game/image_cache.py +61 -0
  70. spriteforge/game/lessons.py +259 -0
  71. spriteforge/game/level_gen.py +118 -0
  72. spriteforge/game/level_preview.py +97 -0
  73. spriteforge/game/levels.py +934 -0
  74. spriteforge/game/loops.py +38 -0
  75. spriteforge/game/menus.py +712 -0
  76. spriteforge/game/mock_game.js +109 -0
  77. spriteforge/game/mock_platformer.js +58 -0
  78. spriteforge/game/motion.py +881 -0
  79. spriteforge/game/pipeline.py +1768 -0
  80. spriteforge/game/plan.py +502 -0
  81. spriteforge/game/playtest.py +318 -0
  82. spriteforge/game/qa.py +664 -0
  83. spriteforge/game/qa_checks.py +223 -0
  84. spriteforge/game/qa_runtime.py +565 -0
  85. spriteforge/game/reach.py +807 -0
  86. spriteforge/game/record.py +138 -0
  87. spriteforge/game/research.py +262 -0
  88. spriteforge/game/revision.py +225 -0
  89. spriteforge/game/sdk/API.md +104 -0
  90. spriteforge/game/sdk/FLOW.md +19 -0
  91. spriteforge/game/sdk/LEVELS.md +65 -0
  92. spriteforge/game/sdk/sf.js +418 -0
  93. spriteforge/game/sdk/sfflow.js +442 -0
  94. spriteforge/game/sdk/sflevel.js +683 -0
  95. spriteforge/game/sdk/sfsound-editor.js +225 -0
  96. spriteforge/game/sdk/sfsound.js +260 -0
  97. spriteforge/game/sdk/sounds.html +67 -0
  98. spriteforge/game/sounds.py +793 -0
  99. spriteforge/game/story.py +188 -0
  100. spriteforge/game/structure.py +98 -0
  101. spriteforge/game/team_reports.py +394 -0
  102. spriteforge/game/tilesets.py +70 -0
  103. spriteforge/game/title_art.py +186 -0
  104. spriteforge/genres/__init__.py +0 -0
  105. spriteforge/library/__init__.py +15 -0
  106. spriteforge/library/cli.py +126 -0
  107. spriteforge/library/describe.py +242 -0
  108. spriteforge/library/looks.py +154 -0
  109. spriteforge/library/models.py +79 -0
  110. spriteforge/library/store.py +422 -0
  111. spriteforge/library/tilesets/README.md +32 -0
  112. spriteforge/library/tilesets/gandalf-seasons.json +111 -0
  113. spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
  114. spriteforge/mcp/__init__.py +0 -0
  115. spriteforge/mcp/cli.py +58 -0
  116. spriteforge/mcp/client.py +57 -0
  117. spriteforge/mcp/filesystem_read.py +32 -0
  118. spriteforge/mcp/gamedb.py +56 -0
  119. spriteforge/mcp/library.py +179 -0
  120. spriteforge/mcp/memory.py +37 -0
  121. spriteforge/mcp/pixel_tools.py +145 -0
  122. spriteforge/mcp/registry.py +145 -0
  123. spriteforge/mcp/service.py +224 -0
  124. spriteforge/mcp/templates/context7.json +6 -0
  125. spriteforge/mcp/templates/fetch.json +6 -0
  126. spriteforge/mcp/templates/filesystem-read.json +6 -0
  127. spriteforge/mcp/templates/pixel-tools.json +6 -0
  128. spriteforge/memory/README.md +10 -0
  129. spriteforge/memory/__init__.py +0 -0
  130. spriteforge/memory/cli.py +131 -0
  131. spriteforge/memory/okf/__init__.py +1 -0
  132. spriteforge/memory/okf/catalog.py +331 -0
  133. spriteforge/memory/okf/codec.py +63 -0
  134. spriteforge/memory/okf/git.py +104 -0
  135. spriteforge/memory/okf/indexes.py +50 -0
  136. spriteforge/memory/okf/models.py +114 -0
  137. spriteforge/memory/okf/search.py +53 -0
  138. spriteforge/memory/okf/seed.py +81 -0
  139. spriteforge/memory/okf/seeds/genres.yaml +121 -0
  140. spriteforge/memory/okf/seeds/other.yaml +150 -0
  141. spriteforge/memory/okf/store.py +402 -0
  142. spriteforge/memory/okf/validate.py +115 -0
  143. spriteforge/pixel/__init__.py +17 -0
  144. spriteforge/pixel/atlas.py +110 -0
  145. spriteforge/pixel/grid.py +174 -0
  146. spriteforge/pixel/palette.py +156 -0
  147. spriteforge/pixel/palettes/dungeon.json +9 -0
  148. spriteforge/pixel/postprocess.py +170 -0
  149. spriteforge/pixel/preview.py +40 -0
  150. spriteforge/pixel/schemas.py +139 -0
  151. spriteforge/pixel/source.py +237 -0
  152. spriteforge/pixel/terrain.py +48 -0
  153. spriteforge/pixel/validate.py +138 -0
  154. spriteforge/prompts/anim_frame.txt +1 -0
  155. spriteforge/prompts/character.txt +1 -0
  156. spriteforge/prompts/item.txt +1 -0
  157. spriteforge/prompts/tile.txt +1 -0
  158. spriteforge/prompts/ui.txt +1 -0
  159. spriteforge/providers/__init__.py +0 -0
  160. spriteforge/providers/base.py +97 -0
  161. spriteforge/providers/http.py +38 -0
  162. spriteforge/providers/mock.py +111 -0
  163. spriteforge/providers/muse_image.py +60 -0
  164. spriteforge/providers/muse_search.py +91 -0
  165. spriteforge/providers/muse_spark.py +66 -0
  166. spriteforge/skills/__init__.py +0 -0
  167. spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
  168. spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
  169. spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
  170. spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
  171. spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
  172. spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
  173. spriteforge/skills/builtin/level-design/SKILL.md +169 -0
  174. spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
  175. spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
  176. spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
  177. spriteforge/skills/builtin/platformer/SKILL.md +153 -0
  178. spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
  179. spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
  180. spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
  181. spriteforge/skills/catalog.py +200 -0
  182. spriteforge/skills/cli.py +41 -0
  183. spriteforge/stages/__init__.py +0 -0
  184. spriteforge/stages/asset_context.py +301 -0
  185. spriteforge/stages/asset_models.py +192 -0
  186. spriteforge/stages/asset_render.py +366 -0
  187. spriteforge/stages/asset_review.py +140 -0
  188. spriteforge/stages/asset_store.py +94 -0
  189. spriteforge/stages/chat_changes.py +236 -0
  190. spriteforge/stages/concept.py +42 -0
  191. spriteforge/stages/game.py +1699 -0
  192. spriteforge/stages/game_confirm.py +112 -0
  193. spriteforge/stages/game_final.py +220 -0
  194. spriteforge/stages/game_record.py +246 -0
  195. spriteforge/stages/gameplay.py +218 -0
  196. spriteforge/stages/intake.py +372 -0
  197. spriteforge/stages/preview_assets.py +212 -0
  198. spriteforge/stages/preview_models.py +167 -0
  199. spriteforge/stages/preview_render.py +169 -0
  200. spriteforge/stages/preview_repair.py +61 -0
  201. spriteforge/stages/preview_review.py +169 -0
  202. spriteforge/stages/production.py +170 -0
  203. spriteforge/stages/references.py +105 -0
  204. spriteforge/stages/rewind.py +128 -0
  205. spriteforge/stages/workflow.py +440 -0
  206. spriteforge/templates/phaser/audit.js +45 -0
  207. spriteforge/templates/phaser/font.png +0 -0
  208. spriteforge/templates/phaser/font.xml +1 -0
  209. spriteforge/templates/phaser/preview.html +9 -0
  210. spriteforge/templates/phaser/room.js +49 -0
  211. spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
  212. spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
  213. spriteforge-0.1.1.dist-info/METADATA +364 -0
  214. spriteforge-0.1.1.dist-info/RECORD +218 -0
  215. spriteforge-0.1.1.dist-info/WHEEL +5 -0
  216. spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
  217. spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
  218. spriteforge-0.1.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,174 @@
1
+ """Big-cell grid recovery for image-model pixel art.
2
+
3
+ Muse Image draws "a 16x16 grid of big square pixels" as ~100 px cells, with a little jitter
4
+ and compression noise. `source.detect_grid` looks for blocks up to 64 px; this finds the cell
5
+ pitch of much larger blocks from the colour boundaries, then reads one colour per cell from
6
+ the cell's centre (median, so noise and soft edges do not matter).
7
+ """
8
+
9
+ from dataclasses import dataclass
10
+ from itertools import pairwise
11
+
12
+ import numpy as np
13
+ from PIL import Image
14
+
15
+ EDGE = 40 # RGB distance that counts as a boundary between two cells
16
+ MIN_PITCH = 4
17
+
18
+
19
+ @dataclass
20
+ class Grid:
21
+ pitch: float
22
+ # How much better these cells explain the image than cells shifted by half a cell:
23
+ # ~1 for big-pixel art, ~0 for painted images (where any cut is as good as another).
24
+ confidence: float
25
+ lines: tuple[list[float], list[float]] # x and y cell edges, in source pixels
26
+
27
+
28
+ def _boundaries(rgba: np.ndarray, axis: int) -> list[float]:
29
+ """Positions (between pixels) where many rows (axis=1) or columns change colour."""
30
+ rgb = rgba[..., :3].astype(np.int16)
31
+ alpha = rgba[..., 3] > 0
32
+ delta = np.linalg.norm(np.diff(rgb, axis=axis), axis=-1) >= EDGE
33
+ flip = np.diff(alpha.astype(np.int8), axis=axis) != 0
34
+ both = np.diff(alpha.astype(np.int8), axis=axis) == 0
35
+ edges = (delta & both & alpha[:, 1:] if axis == 1 else delta & both & alpha[1:]) | flip
36
+ profile = edges.sum(axis=1 - axis).astype(float)
37
+ if not profile.any():
38
+ return []
39
+ marked = np.flatnonzero(profile >= max(2.0, 0.02 * profile.max()))
40
+ groups = np.split(marked, np.flatnonzero(np.diff(marked) > 3) + 1)
41
+ groups = [g for g in groups if len(g)]
42
+ mass = np.array([profile[g].sum() for g in groups])
43
+ # Short edges (half-cell details, soft shading) are much weaker than real cell edges.
44
+ strong = mass >= 0.25 * np.percentile(mass, 75)
45
+ return [float(np.average(g, weights=profile[g])) + 1 for g, k in zip(groups, strong) if k]
46
+
47
+
48
+ def _pitch(gaps: np.ndarray, top: float) -> float | None:
49
+ """The most common one-cell gap: the pitch with the most gaps within 10% of it."""
50
+ gaps = gaps[gaps >= MIN_PITCH * 0.9]
51
+ if not len(gaps):
52
+ return None
53
+ # 0.5% steps from MIN_PITCH to `top`
54
+ candidates = MIN_PITCH * 1.005 ** np.arange(int(np.log(top / MIN_PITCH) / np.log(1.005)) + 1)
55
+ near = np.abs(gaps[None, :] - candidates[:, None]) <= 0.1 * candidates[:, None]
56
+ best = candidates[near.sum(axis=1).argmax()]
57
+ return float(np.median(gaps[np.abs(gaps - best) <= 0.1 * best]))
58
+
59
+
60
+ def detect_cells(
61
+ image: Image.Image, min_boundaries: int = 8, pitch: float | None = None
62
+ ) -> Grid | None:
63
+ """Cell edges of a big-pixel image, or None. Image models draw cells of slightly uneven
64
+ size, a little different per axis, with the odd half-cell detail, so the edges are the
65
+ detected colour boundaries themselves, with a line added inside every gap that spans
66
+ several cells and edges closer than half a cell skipped. `pitch` skips the estimate
67
+ (frames of one sprite sheet share the pitch they were drawn at)."""
68
+ rgba = np.asarray(image.convert("RGBA"))
69
+ axes = [np.array(_boundaries(rgba, 1)), np.array(_boundaries(rgba, 0))]
70
+ if min(len(a) for a in axes) < 2 or sum(len(a) for a in axes) < min_boundaries:
71
+ return None
72
+ gaps = np.concatenate([np.diff(a) for a in axes])
73
+ pitch = pitch or _pitch(gaps, max(MIN_PITCH, min(image.size) / 2))
74
+ if pitch is None:
75
+ return None
76
+ lines = tuple(
77
+ _lines(np.concatenate([[0.0], a, [float(n)]]), _axis_pitch(a, pitch))
78
+ for a, n in zip(axes, image.size, strict=True)
79
+ )
80
+ if min(len(ls) for ls in lines) < 3:
81
+ return None # fewer than two cells on an axis: nothing to read back
82
+ aligned = _purity(rgba, lines)
83
+ shifted = _purity(rgba, tuple([(a + b) / 2 for a, b in pairwise(ls)] for ls in lines))
84
+ confidence = max(0.0, (aligned - shifted) / (1 - shifted)) if shifted < 1 else 0.0
85
+ return Grid(pitch, confidence, lines)
86
+
87
+
88
+ def _axis_pitch(found: np.ndarray, pitch: float) -> float:
89
+ """This axis's own one-cell gap (models draw cells a little wider than tall, or not)."""
90
+ gaps = np.diff(found)
91
+ single = gaps[np.abs(gaps - pitch) <= 0.15 * pitch]
92
+ return float(np.median(single)) if len(single) >= 3 else pitch
93
+
94
+
95
+ def _lines(found: np.ndarray, pitch: float) -> list[float]:
96
+ """Cell edges from sorted boundaries (image edges included)."""
97
+ found = np.unique(found)
98
+ lines = [float(found[0])]
99
+ for b in found[1:]:
100
+ n = round((b - lines[-1]) / pitch)
101
+ if n == 0:
102
+ continue # a detail inside a cell, or the image edge just past the last line
103
+ start = lines[-1]
104
+ lines += [start + (b - start) * i / n for i in range(1, n + 1)]
105
+ if found[-1] - lines[-1] > pitch / 2:
106
+ lines.append(float(found[-1]))
107
+ return lines
108
+
109
+
110
+ def _patches(rgba: np.ndarray, lines, share: float) -> np.ndarray:
111
+ """The centre patch of every cell, `share` of the smallest cell's side, as one array
112
+ (rows, cols, pixels, 4); patch pixels outside the image are transparent."""
113
+ xs, ys = (np.array(v) for v in lines)
114
+ side = max(1, int(share * min(np.diff(xs).min(), np.diff(ys).min())))
115
+ cx, cy = (xs[:-1] + xs[1:]) / 2, (ys[:-1] + ys[1:]) / 2
116
+ offsets = np.arange(side) - (side - 1) / 2
117
+ px = np.round(cx[:, None] + offsets[None, :]).astype(int) # (cols, side)
118
+ py = np.round(cy[:, None] + offsets[None, :]).astype(int) # (rows, side)
119
+ padded = np.pad(rgba, ((1, 1), (1, 1), (0, 0))) # index -1 / size -> transparent border
120
+ px = np.clip(px + 1, 0, padded.shape[1] - 1)
121
+ py = np.clip(py + 1, 0, padded.shape[0] - 1)
122
+ patch = padded[py[:, None, :, None], px[None, :, None, :]] # (rows, cols, side, side, 4)
123
+ return patch.reshape(len(cy), len(cx), side * side, 4)
124
+
125
+
126
+ def _purity(rgba: np.ndarray, lines) -> float:
127
+ """Share of opaque pixels within a small distance of their cell's median colour, over
128
+ cells that are mostly opaque."""
129
+ patch = _patches(rgba, lines, 0.7)
130
+ opaque = patch[..., 3] > 0
131
+ cells = opaque.mean(axis=-1) > 0.5
132
+ if not cells.any():
133
+ return 0.0
134
+ rgb = patch[cells][..., :3].astype(int) # (cells, pixels, 3)
135
+ keep = opaque[cells]
136
+ median = np.nanmedian(np.where(keep[..., None], rgb, np.nan), axis=1)
137
+ near = (np.abs(rgb - median[:, None, :]).sum(axis=-1) <= 45) & keep
138
+ return float(near.sum() / keep.sum())
139
+
140
+
141
+ def sample_cells(image: Image.Image, grid: Grid) -> Image.Image:
142
+ """One pixel per cell: the median colour of the cell's centre; transparent if mostly so."""
143
+ patch = _patches(np.asarray(image.convert("RGBA")), grid.lines, 0.5)
144
+ opaque = patch[..., 3] > 0
145
+ cells = opaque.mean(axis=-1) > 0.5
146
+ out = np.zeros((*patch.shape[:2], 4), dtype=np.uint8)
147
+ rgb = np.where(opaque[..., None], patch[..., :3].astype(float), np.nan)
148
+ with np.errstate(all="ignore"):
149
+ median = np.nan_to_num(np.nanmedian(rgb[cells], axis=1)) if cells.any() else 0
150
+ out[cells, :3] = np.round(median)
151
+ out[cells, 3] = 255
152
+ return Image.fromarray(merge_close(out))
153
+
154
+
155
+ def merge_close(rgba: np.ndarray, distance: float = 12) -> np.ndarray:
156
+ """Cells of one drawn colour come back a few values apart (noise, JPEG): give each group
157
+ of near-identical colours its most common member."""
158
+ opaque = rgba[..., 3] > 0
159
+ if not opaque.any():
160
+ return rgba
161
+ colors, inverse, counts = np.unique(
162
+ rgba[opaque][:, :3], axis=0, return_inverse=True, return_counts=True
163
+ )
164
+ reps: list[np.ndarray] = []
165
+ mapped = np.empty_like(colors)
166
+ for i in np.argsort(-counts, kind="stable"):
167
+ near = [r for r in reps if np.linalg.norm(colors[i].astype(float) - r) <= distance]
168
+ if not near:
169
+ reps.append(colors[i].astype(float))
170
+ near = [reps[-1]]
171
+ mapped[i] = near[0]
172
+ out = rgba.copy()
173
+ out[opaque, :3] = mapped[inverse.reshape(-1)]
174
+ return out
@@ -0,0 +1,156 @@
1
+ """D65 CIELAB conversion, deterministic weighted k-means, and palette files."""
2
+
3
+ import json
4
+ from pathlib import Path
5
+
6
+ import numpy as np
7
+ from PIL import Image
8
+
9
+ from .schemas import Palette
10
+
11
+ WHITE = np.array([0.95047, 1.0, 1.08883])
12
+ RGB_TO_XYZ = np.array(
13
+ [
14
+ [0.4124564, 0.3575761, 0.1804375],
15
+ [0.2126729, 0.7151522, 0.0721750],
16
+ [0.0193339, 0.1191920, 0.9503041],
17
+ ]
18
+ )
19
+
20
+
21
+ def rgb_to_lab(rgb: np.ndarray) -> np.ndarray:
22
+ rgb = np.asarray(rgb, dtype=np.float64) / 255
23
+ linear = np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
24
+ xyz = (linear @ RGB_TO_XYZ.T) / WHITE
25
+ f = np.where(xyz > (6 / 29) ** 3, np.cbrt(xyz), xyz / (3 * (6 / 29) ** 2) + 4 / 29)
26
+ return np.stack(
27
+ [116 * f[..., 1] - 16, 500 * (f[..., 0] - f[..., 1]), 200 * (f[..., 1] - f[..., 2])],
28
+ axis=-1,
29
+ )
30
+
31
+
32
+ def lab_to_rgb(lab: np.ndarray) -> np.ndarray:
33
+ lab = np.asarray(lab, dtype=np.float64)
34
+ fy = (lab[..., 0] + 16) / 116
35
+ f = np.stack([fy + lab[..., 1] / 500, fy, fy - lab[..., 2] / 200], axis=-1)
36
+ xyz = np.where(f > 6 / 29, f**3, 3 * (6 / 29) ** 2 * (f - 4 / 29)) * WHITE
37
+ linear = np.clip(xyz @ np.linalg.inv(RGB_TO_XYZ).T, 0, 1)
38
+ rgb = np.where(linear <= 0.0031308, 12.92 * linear, 1.055 * linear ** (1 / 2.4) - 0.055)
39
+ return np.rint(rgb * 255).clip(0, 255).astype(np.uint8)
40
+
41
+
42
+ def palette_rgb(colors: list[str]) -> np.ndarray:
43
+ return np.array([[int(c[i : i + 2], 16) for i in (1, 3, 5)] for c in colors], dtype=np.uint8)
44
+
45
+
46
+ def nearest_indices(points: np.ndarray, centers: np.ndarray) -> np.ndarray:
47
+ labels = np.empty(len(points), dtype=np.int32)
48
+ for start in range(0, len(points), 8192):
49
+ chunk = points[start : start + 8192]
50
+ labels[start : start + len(chunk)] = ((chunk[:, None] - centers) ** 2).sum(-1).argmin(-1)
51
+ return labels
52
+
53
+
54
+ def quantize(rgb: np.ndarray, colors: list[str]) -> np.ndarray:
55
+ table = palette_rgb(colors)
56
+ flat = np.asarray(rgb).reshape(-1, 3)
57
+ # Work on unique colors to keep large flat sheets inexpensive.
58
+ unique, inverse = np.unique(flat, axis=0, return_inverse=True)
59
+ labels = nearest_indices(rgb_to_lab(unique), rgb_to_lab(table))
60
+ return table[labels[inverse]].reshape(np.asarray(rgb).shape)
61
+
62
+
63
+ def merge_near_duplicates(palette: Palette, threshold: float = 5) -> Palette:
64
+ if threshold < 0:
65
+ raise ValueError("threshold must be nonnegative")
66
+ lab = rgb_to_lab(palette_rgb(palette.colors))
67
+ kept = []
68
+ for i, color in enumerate(lab):
69
+ if not kept or np.linalg.norm(lab[kept] - color, axis=1).min() > threshold:
70
+ kept.append(i)
71
+ return Palette(name=palette.name, colors=[palette.colors[i] for i in kept])
72
+
73
+
74
+ def extract_palette(
75
+ image: Image.Image, count: int = 16, merge_threshold: float = 5, max_iterations: int = 30
76
+ ) -> Palette:
77
+ if not 1 <= count <= 256 or max_iterations < 1:
78
+ raise ValueError("count must be 1..256 and iterations must be positive")
79
+ pixels = np.asarray(image.convert("RGBA"))
80
+ rgb = pixels[..., :3][pixels[..., 3] > 0]
81
+ if not len(rgb):
82
+ raise ValueError("Cannot extract a palette from an entirely transparent image")
83
+ # Fixed evenly-spaced sample, no random seed or process-dependent initialization.
84
+ if len(rgb) > 16384:
85
+ rgb = rgb[np.linspace(0, len(rgb) - 1, 16384, dtype=int)]
86
+ unique, weights = np.unique(rgb, axis=0, return_counts=True)
87
+ points = rgb_to_lab(unique)
88
+ count = min(count, len(points))
89
+ centers = [points[weights.argmax()]]
90
+ while len(centers) < count:
91
+ distance = ((points[:, None] - np.array(centers)) ** 2).sum(-1).min(-1)
92
+ centers.append(points[(distance * weights).argmax()])
93
+ centers = np.array(centers)
94
+ for _ in range(max_iterations):
95
+ labels = nearest_indices(points, centers)
96
+ updated = centers.copy()
97
+ for i in range(count):
98
+ mask = labels == i
99
+ if mask.any():
100
+ updated[i] = np.average(points[mask], axis=0, weights=weights[mask])
101
+ if np.allclose(updated, centers, atol=1e-5):
102
+ break
103
+ centers = updated
104
+ colors = ["#" + "".join(f"{v:02X}" for v in row) for row in lab_to_rgb(centers)]
105
+ return merge_near_duplicates(Palette(name="extracted", colors=colors), merge_threshold)
106
+
107
+
108
+ def load_palette(path_or_name: str | Path) -> Palette:
109
+ path = Path(path_or_name)
110
+ if not path.is_file() and isinstance(path_or_name, str) and path.name == path_or_name:
111
+ path = Path(__file__).with_name("palettes") / (path_or_name + ".json")
112
+ return Palette.model_validate_json(path.read_text(encoding="utf-8"))
113
+
114
+
115
+ def save_palette(palette: Palette, path: Path) -> None:
116
+ path.parent.mkdir(parents=True, exist_ok=True)
117
+ path.write_text(json.dumps(palette.model_dump(), indent=2) + "\n", encoding="utf-8")
118
+
119
+
120
+ def palette_usage(image: Image.Image, palette: Palette) -> dict[str, int]:
121
+ """Count visible pixels, including zero counts for unused palette entries."""
122
+ rgba = np.asarray(image.convert("RGBA"))
123
+ colors, counts = np.unique(rgba[..., :3][rgba[..., 3] > 0], axis=0, return_counts=True)
124
+ used = {
125
+ "#" + "".join(f"{v:02X}" for v in rgb): int(n)
126
+ for rgb, n in zip(colors, counts, strict=True)
127
+ }
128
+ return {color: used.get(color, 0) for color in palette.colors}
129
+
130
+
131
+ def background_tinted_dark_colors(
132
+ palette: Palette,
133
+ background: str | None,
134
+ dark_lightness: float = 35,
135
+ hue_similarity: float = 0.75,
136
+ ) -> list[str]:
137
+ """Flag chromatic dark colors whose LAB hue points toward the key background.
138
+
139
+ This is a warning, not an automatic edit: legitimate purple outlines may qualify.
140
+ Neutral colors (chroma < 10) and neutral backgrounds are excluded.
141
+ """
142
+ if background is None:
143
+ return []
144
+ bg = rgb_to_lab(palette_rgb([background]))[0, 1:]
145
+ if np.linalg.norm(bg) < 15:
146
+ return []
147
+ lab = rgb_to_lab(palette_rgb(palette.colors))
148
+ chroma = np.linalg.norm(lab[:, 1:], axis=1)
149
+ cosine = (lab[:, 1:] @ bg) / (np.maximum(chroma, 1e-9) * np.linalg.norm(bg))
150
+ return [
151
+ color
152
+ for color, value, magnitude, similarity in zip(
153
+ palette.colors, lab, chroma, cosine, strict=True
154
+ )
155
+ if value[0] <= dark_lightness and magnitude >= 10 and similarity >= hue_similarity
156
+ ]
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "dungeon",
3
+ "colors": [
4
+ "#171725", "#35354A", "#57546B", "#8B8294",
5
+ "#D7CED1", "#FFFFFF", "#173F35", "#256B43",
6
+ "#47AD59", "#9CDD74", "#603F37", "#A36B46",
7
+ "#E4B765", "#A4394A", "#EB6972", "#647DC6"
8
+ ]
9
+ }
@@ -0,0 +1,170 @@
1
+ import math
2
+
3
+ import numpy as np
4
+ from PIL import Image
5
+
6
+ from .palette import background_tinted_dark_colors, palette_rgb, palette_usage, quantize, rgb_to_lab
7
+ from .schemas import AssetSpec, Palette, ProcessingOptions, ProcessingReport, Style
8
+ from .source import mode_resize, prepare_source
9
+
10
+
11
+ def boundary_already_dark(image: Image.Image, style: Style) -> bool:
12
+ rgba = np.asarray(image.convert("RGBA"))
13
+ mask = rgba[..., 3] > 0
14
+ p = np.pad(mask, 1)
15
+ interior = p[:-2, 1:-1] & p[2:, 1:-1] & p[1:-1, :-2] & p[1:-1, 2:]
16
+ boundary = mask & ~interior
17
+ colors = rgb_to_lab(palette_rgb(style.palette))
18
+ dark = colors[colors[:, 0] <= style.outline_dark_lightness]
19
+ if not boundary.any() or not len(dark):
20
+ return False
21
+ distance = np.linalg.norm(rgb_to_lab(rgba[..., :3][boundary])[:, None] - dark, axis=-1).min(-1)
22
+ return float(np.mean(distance <= style.outline_dark_tolerance)) > 0.9
23
+
24
+
25
+ def _record_palette(result: Image.Image, style: Style, report: ProcessingReport) -> None:
26
+ palette = Palette(colors=style.palette)
27
+ report.palette_size = len(palette.colors)
28
+ report.palette_usage = palette_usage(result, palette)
29
+ report.tinted_dark_colors = background_tinted_dark_colors(palette, report.background)
30
+ report.warnings.extend(
31
+ f"Unused palette color: {color}" for color, n in report.palette_usage.items() if n == 0
32
+ )
33
+ report.warnings.extend(
34
+ f"Dark palette color {color} is tinted toward background {report.background}."
35
+ for color in report.tinted_dark_colors
36
+ )
37
+
38
+
39
+ def remove_clusters(alpha: np.ndarray, minimum: int) -> np.ndarray:
40
+ """Remove 4-connected components smaller than minimum; diagonal pixels are separate."""
41
+ keep = alpha.copy()
42
+ seen = np.zeros(alpha.shape, dtype=bool)
43
+ height, width = alpha.shape
44
+ for y, x in np.argwhere(alpha > 0):
45
+ if seen[y, x]:
46
+ continue
47
+ todo, cluster = [(int(y), int(x))], []
48
+ seen[y, x] = True
49
+ while todo:
50
+ cy, cx = todo.pop()
51
+ cluster.append((cy, cx))
52
+ for ny, nx in ((cy - 1, cx), (cy + 1, cx), (cy, cx - 1), (cy, cx + 1)):
53
+ if 0 <= ny < height and 0 <= nx < width and alpha[ny, nx] and not seen[ny, nx]:
54
+ seen[ny, nx] = True
55
+ todo.append((ny, nx))
56
+ if len(cluster) < minimum:
57
+ yy, xx = zip(*cluster, strict=True)
58
+ keep[yy, xx] = 0
59
+ return keep
60
+
61
+
62
+ def postprocess(
63
+ raw: Image.Image,
64
+ spec: AssetSpec,
65
+ style: Style,
66
+ *,
67
+ options: ProcessingOptions | None = None,
68
+ report: ProcessingReport | None = None,
69
+ ) -> Image.Image:
70
+ report = report if report is not None else ProcessingReport()
71
+ if options is not None:
72
+ raw = prepare_source(raw, options, report)
73
+ pixels = np.array(raw.convert("RGBA"))
74
+ key = palette_rgb([style.background])[0].astype(float)
75
+ distance = np.linalg.norm(pixels[..., :3].astype(float) - key, axis=-1)
76
+ if options is None:
77
+ pixels[distance <= style.chroma_tolerance, 3] = 0
78
+ # Transparent RGB must not bleed into BOX coverage/color averaging.
79
+ pixels[pixels[..., 3] == 0] = 0
80
+ keyed = Image.fromarray(pixels)
81
+ bbox = keyed.getbbox()
82
+ if bbox is None:
83
+ empty = Image.new("RGBA", spec.size)
84
+ _record_palette(empty, style, report)
85
+ return empty
86
+ cropped = keyed.crop(bbox)
87
+ add_outline = style.outline and not boundary_already_dark(cropped, style)
88
+ # Reserve one further output pixel for the external 4-neighbor outline.
89
+ margin = spec.margin + int(add_outline and spec.type != "tile")
90
+ available = (spec.size[0] - 2 * margin, spec.size[1] - 2 * margin)
91
+ if min(available) < 1:
92
+ raise ValueError("Canvas has no room for padding and outline")
93
+ native = (
94
+ options is not None
95
+ and options.scale_mode != "fit"
96
+ and report.logical_subject_size is not None
97
+ )
98
+ content = None
99
+ if native:
100
+ factor = max(1, math.ceil(max(cropped.width / available[0], cropped.height / available[1])))
101
+ if factor == 1:
102
+ content = cropped
103
+ report.scale_mode, report.scale_factor = "native", 1.0
104
+ else:
105
+ suggested = max(cropped.width + 2 * margin, cropped.height + 2 * margin)
106
+ report.warnings.append(
107
+ f"Logical subject {cropped.width}x{cropped.height} exceeds usable canvas "
108
+ f"{available[0]}x{available[1]}; downscaling. Use --size {suggested} or larger for 1:1 pixels."
109
+ )
110
+ if cropped.width % factor == 0 and cropped.height % factor == 0:
111
+ content = mode_resize(cropped, (cropped.width // factor, cropped.height // factor))
112
+ report.scale_mode, report.scale_factor = "native-integer-downscale", 1 / factor
113
+ else:
114
+ report.scale_mode = "native-mode-downscale"
115
+ elif options is not None and options.scale_mode == "native":
116
+ report.warnings.append(
117
+ "No confident source grid detected; native placement unavailable, using fit."
118
+ )
119
+ if content is not None:
120
+ canvas = Image.new("RGBA", spec.size)
121
+ y = (
122
+ spec.size[1] - margin - content.height
123
+ if options.baseline == "bottom"
124
+ else (spec.size[1] - content.height) // 2
125
+ )
126
+ canvas.paste(content, ((spec.size[0] - content.width) // 2, y))
127
+ pixels = np.array(canvas)
128
+ else:
129
+ scale = max(1, math.ceil(max(cropped.width / available[0], cropped.height / available[1])))
130
+ canvas_size = (spec.size[0] * scale, spec.size[1] * scale)
131
+ fit = min(available[0] * scale / cropped.width, available[1] * scale / cropped.height)
132
+ content_size = (max(1, round(cropped.width * fit)), max(1, round(cropped.height * fit)))
133
+ report.scale_factor = fit / scale
134
+ content = cropped.resize(content_size, Image.Resampling.NEAREST)
135
+ canvas = Image.new("RGBA", canvas_size)
136
+ y = (
137
+ canvas.height - margin * scale - content.height
138
+ if options and options.baseline == "bottom"
139
+ else (canvas.height - content.height) // 2
140
+ )
141
+ canvas.paste(content, ((canvas.width - content.width) // 2, y))
142
+ pixels = np.array(
143
+ mode_resize(canvas, spec.size)
144
+ if options is not None
145
+ else canvas.resize(spec.size, Image.Resampling.BOX)
146
+ )
147
+ pixels[..., :3] = quantize(pixels[..., :3], style.palette)
148
+ pixels[..., 3] = np.where(pixels[..., 3] >= style.alpha_threshold, 255, 0)
149
+ pixels[..., 3] = remove_clusters(pixels[..., 3], style.min_cluster_size)
150
+ if add_outline and not boundary_already_dark(Image.fromarray(pixels), style):
151
+ mask = pixels[..., 3] > 0
152
+ padded = np.pad(mask, 1)
153
+ neighbors = padded[:-2, 1:-1] | padded[2:, 1:-1] | padded[1:-1, :-2] | padded[1:-1, 2:]
154
+ if options is not None:
155
+ # Fill diagonal corners too: a real-output outline must be 4-connected,
156
+ # rather than four separate sides around a rectangular subject.
157
+ neighbors |= padded[:-2, :-2] | padded[:-2, 2:] | padded[2:, :-2] | padded[2:, 2:]
158
+ border = neighbors & ~mask
159
+ colors = palette_rgb(style.palette)
160
+ dark = (
161
+ palette_rgb([style.outline_color])[0]
162
+ if style.outline_color
163
+ else colors[rgb_to_lab(colors)[:, 0].argmin()]
164
+ )
165
+ pixels[border, :3] = dark
166
+ pixels[border, 3] = 255
167
+ pixels[pixels[..., 3] == 0] = 0
168
+ result = Image.fromarray(pixels)
169
+ _record_palette(result, style, report)
170
+ return result
@@ -0,0 +1,40 @@
1
+ import math
2
+ from collections.abc import Mapping
3
+
4
+ from PIL import Image, ImageDraw
5
+
6
+
7
+ def upscale(image: Image.Image, factor: int = 8) -> Image.Image:
8
+ if factor < 1:
9
+ raise ValueError("factor must be a positive integer")
10
+ return image.resize((image.width * factor, image.height * factor), Image.Resampling.NEAREST)
11
+
12
+
13
+ def contact_sheet(
14
+ images: Mapping[str, Image.Image], columns: int = 4, factor: int = 8, gap: int = 12
15
+ ) -> Image.Image:
16
+ if not images or columns < 1 or factor < 1 or gap < 0:
17
+ raise ValueError("Need images, positive columns/factor, and nonnegative gap")
18
+ cell_width = max(160, max(image.width for image in images.values()) * factor)
19
+ cell_height = max(image.height for image in images.values()) * factor + 24
20
+ columns = min(columns, len(images))
21
+ rows = math.ceil(len(images) / columns)
22
+ sheet = Image.new(
23
+ "RGBA", (columns * (cell_width + gap) + gap, rows * (cell_height + gap) + gap), "#202536"
24
+ )
25
+ draw = ImageDraw.Draw(sheet)
26
+ for i, (name, image) in enumerate(images.items()):
27
+ x = gap + (i % columns) * (cell_width + gap)
28
+ y = gap + (i // columns) * (cell_height + gap)
29
+ large = upscale(image.convert("RGBA"), factor)
30
+ sheet.alpha_composite(large, (x + (cell_width - large.width) // 2, y))
31
+ draw.text((x, y + cell_height - 18), name, fill="white")
32
+ return sheet
33
+
34
+
35
+ def comparison(before: Image.Image, after: Image.Image, factor: int = 8) -> Image.Image:
36
+ """Compare raw downscaled without correction against the clean sprite at equal scale."""
37
+ naive = before.convert("RGBA").resize(after.size, Image.Resampling.BOX)
38
+ return contact_sheet(
39
+ {"Raw, BOX downscale": naive, "Harness output": after}, columns=2, factor=factor
40
+ )