spine-atlas-toolkit 1.0.0__tar.gz
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.
- spine_atlas_toolkit-1.0.0/.gitignore +37 -0
- spine_atlas_toolkit-1.0.0/CHANGELOG.md +349 -0
- spine_atlas_toolkit-1.0.0/LIBRARY.md +198 -0
- spine_atlas_toolkit-1.0.0/LICENSE +202 -0
- spine_atlas_toolkit-1.0.0/NOTICE +14 -0
- spine_atlas_toolkit-1.0.0/PKG-INFO +220 -0
- spine_atlas_toolkit-1.0.0/README.md +62 -0
- spine_atlas_toolkit-1.0.0/THIRD_PARTY_NOTICES.md +14 -0
- spine_atlas_toolkit-1.0.0/pyproject.toml +58 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/__init__.py +29 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/alpha_mode.py +27 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/api.py +968 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/document.py +593 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/__init__.py +2 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/alpha_split.py +89 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/bleed.py +45 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/converter.py +168 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/effective_model.py +74 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/packing.py +755 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/region_ops.py +83 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/domain/region_validation.py +61 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/__init__.py +5 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/_images.py +87 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/composite_split.py +190 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/extraction.py +297 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/modifier.py +1189 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/engine/session.py +1144 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/mesh/__init__.py +2 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/mesh/lookup.py +34 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/packer.py +169 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/raster/__init__.py +2 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/raster/base.py +191 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/raster/lanczos.py +139 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/raster/pillow_backend.py +385 -0
- spine_atlas_toolkit-1.0.0/spine_atlas_toolkit/raster/premultiplied.py +43 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Python-generated files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[oc]
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
wheels/
|
|
7
|
+
*.egg-info
|
|
8
|
+
|
|
9
|
+
# Virtual environments
|
|
10
|
+
.venv
|
|
11
|
+
|
|
12
|
+
# Node build tooling (esbuild for the web/desktop bundle)
|
|
13
|
+
node_modules/
|
|
14
|
+
|
|
15
|
+
# Editor
|
|
16
|
+
.vscode
|
|
17
|
+
.claude
|
|
18
|
+
CONTEXT.md
|
|
19
|
+
CLAUDE.md
|
|
20
|
+
|
|
21
|
+
# Scratch test files (stray root-level test scripts), but not the real
|
|
22
|
+
# committed test suite in /tests/
|
|
23
|
+
test*
|
|
24
|
+
!/tests/
|
|
25
|
+
!/tests/**
|
|
26
|
+
tests/**/__pycache__/
|
|
27
|
+
tests/**/*.py[cod]
|
|
28
|
+
|
|
29
|
+
# Superpowers SDD scratch (local only)
|
|
30
|
+
.superpowers
|
|
31
|
+
|
|
32
|
+
# Worktrees (local scratch, not part of repo)
|
|
33
|
+
.worktrees
|
|
34
|
+
# Real-world atlas fixtures for the pixel-oracle harness (local scratch data)
|
|
35
|
+
.workspaces
|
|
36
|
+
tests/browser/ground_truth_ops.local.json
|
|
37
|
+
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to AtlasToolkit. Versions match the Git tags and the
|
|
4
|
+
[GitHub Releases](https://github.com/com55/AtlasToolkit/releases), which carry
|
|
5
|
+
the full notes and screenshots.
|
|
6
|
+
|
|
7
|
+
## [1.0.0] - 2026-11-21 - Python engine
|
|
8
|
+
|
|
9
|
+
App 1.0.0 and library `spine-atlas-toolkit` 1.0.0. From here on the two have
|
|
10
|
+
separate versions: the app's is `APP_VERSION`, the library's
|
|
11
|
+
`spine_atlas_toolkit.__version__`.
|
|
12
|
+
|
|
13
|
+
A Python port of the atlas engine, usable as a library (`spine_atlas_toolkit`,
|
|
14
|
+
on PyPI as `spine-atlas-toolkit`). The apps run the Python engine too: the
|
|
15
|
+
web/PWA app in a Pyodide worker, the desktop app through a local server.
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
- About dialog (the "i" at the right of the status bar): app and library
|
|
19
|
+
versions, the runtime and the third-party packages this build uses, and the
|
|
20
|
+
license texts.
|
|
21
|
+
|
|
22
|
+
### Breaking: package name and public API
|
|
23
|
+
- The library is the `spine-atlas-toolkit` distribution and is imported as
|
|
24
|
+
`spine_atlas_toolkit` (it was `atlas_toolkit`, never published).
|
|
25
|
+
- The app's own code (the host the UI calls, the desktop shell and the
|
|
26
|
+
updater) moved to a separate `atlas_toolkit_app` package that is not
|
|
27
|
+
published. `SpineAtlas` methods that exist only for the app are now
|
|
28
|
+
`_app_pack`, `_app_pack_is_cached`, `_app_transaction`, `_app_region_views`,
|
|
29
|
+
`_app_mesh_hull_layout` and `_app_validate_region_name`, and `RegionView` is
|
|
30
|
+
no longer exported.
|
|
31
|
+
|
|
32
|
+
### Breaking: `PackOptions`
|
|
33
|
+
- `build()` and `save()` take one
|
|
34
|
+
`options=PackOptions(...)` instead of `packer=`, `packer_options=` and
|
|
35
|
+
`split_composite=`. `PackerOptions` is gone; the old keywords raise
|
|
36
|
+
`TypeError`.
|
|
37
|
+
- `PackOptions` fields: `packer` (`"auto"` default, `"shelf"`, `"rectangles"`,
|
|
38
|
+
`"polygons"`), `padding`, `mesh_aware`, `try_keep_layout` (default True),
|
|
39
|
+
`bleed`, `share_composite_image` (default False).
|
|
40
|
+
`"grid"`, `"rectangles_in_place"` and `"polygons_in_place"` are no longer
|
|
41
|
+
packer names: keep the layout with `try_keep_layout=True` and any packer.
|
|
42
|
+
`PackerOptions(repack="always")` is `try_keep_layout=False`;
|
|
43
|
+
`split_composite=True` is the new default, and `split_composite=False` is
|
|
44
|
+
`share_composite_image=True`.
|
|
45
|
+
- Default packer is `"auto"`: `"polygons"` when the atlas has usable mesh
|
|
46
|
+
data, otherwise `"rectangles"` (it was `"shelf"`).
|
|
47
|
+
- Default output changes: pages with a replace or remove now try to keep their
|
|
48
|
+
layout instead of being repacked; a `replace_composite` image is cut into
|
|
49
|
+
pieces per region by default (it used to be shared whole); auto bleed is now
|
|
50
|
+
on by default, since it follows the split.
|
|
51
|
+
- One old combination has no equivalent: `repack="auto"` used to patch an
|
|
52
|
+
add-only page in the same build that repacked a page with a replace or
|
|
53
|
+
remove. `try_keep_layout` is one switch for every page.
|
|
54
|
+
|
|
55
|
+
### Breaking
|
|
56
|
+
- Mesh-aware packing now applies to `pma: true` pages. `mesh_aware=None`
|
|
57
|
+
(the default) masks them to their mesh hulls whenever mesh data is usable;
|
|
58
|
+
opt out with `PackOptions(mesh_aware=False)`. `packer="polygons"` now
|
|
59
|
+
nests and masks pma pages by their mesh hulls too; it always uses the mesh,
|
|
60
|
+
so the only opt-out there is another packer. `mesh_crop=True` now crops
|
|
61
|
+
regions on pma pages too, clearing all four channels outside the hull.
|
|
62
|
+
|
|
63
|
+
### Added
|
|
64
|
+
- `PackOptions(bleed=...)`: Spine's packer Bleed. On every page a build
|
|
65
|
+
writes that is not pma, transparent pixels within 2 px of an image take the
|
|
66
|
+
mean colour of their visible neighbours (alpha stays 0), so linear texture
|
|
67
|
+
filtering draws no dark edges. `None` (default) bleeds when the build
|
|
68
|
+
splits composites (with `share_composite_image=False`, the default);
|
|
69
|
+
`True` / `False` force it. Untouched and rename-only pages keep their pixels.
|
|
70
|
+
- `PackOptions(try_keep_layout=True)` (default): a page whose edits
|
|
71
|
+
fit keeps its layout. Removed regions leave empty space; a replaced region
|
|
72
|
+
whose new pixels fit its old slot (the canvas size `extract()` gives,
|
|
73
|
+
nothing visible outside the old trimmed rect, pixels shared with an
|
|
74
|
+
overlapping neighbour unchanged) is drawn there with its rect and offsets
|
|
75
|
+
unchanged; when composites are split, each piece is drawn into its region's
|
|
76
|
+
slot if the image is that region's canvas size and the piece meets the
|
|
77
|
+
same rules (with `share_composite_image=True` a page holding such a replace
|
|
78
|
+
is repacked); additions go into free space. Any other
|
|
79
|
+
edited page is repacked with the selected packer (including "shelf").
|
|
80
|
+
`PackOptions(try_keep_layout=False)` repacks every edited page.
|
|
81
|
+
Kept-layout pages are not deduplicated afresh: regions that become pixel-identical
|
|
82
|
+
keep their own rects. Vacating a rect or pasting a mod can clear
|
|
83
|
+
never-rendered pixels of an overlapping hulled region, so its extract()
|
|
84
|
+
without mesh_crop may change; what Spine renders does not. Python engine
|
|
85
|
+
only; the JavaScript apps have no in-place modes.
|
|
86
|
+
- `SpineAtlas`: open an atlas from disk (`open`) or memory (`load`), list
|
|
87
|
+
regions, extract single, all or composite sprites (with Forced Resizing and
|
|
88
|
+
Mesh Cropping), record edits (`replace`, `replace_composite`, `add_region`,
|
|
89
|
+
`rename_region`, `remove_region`) and pack them once with `build()` /
|
|
90
|
+
`save()` (`PackOptions`: packer, padding, mesh-aware, keep-layout, bleed).
|
|
91
|
+
- `PackOptions(share_composite_image=False)` (default): a `replace_composite`
|
|
92
|
+
image is cut back into one piece per region, the inverse of
|
|
93
|
+
`extract_composite(force_resize=True)`.
|
|
94
|
+
When the build is mesh-aware (the default with mesh data) each meshed region
|
|
95
|
+
keeps its mesh hull; a semi-transparent pixel shared by several regions has
|
|
96
|
+
its alpha split between them, so drawing them all gives the image back.
|
|
97
|
+
- Multi-page atlases can be edited, including Add, Rename and Remove. Only
|
|
98
|
+
pages that own an edited region are repacked. `add_region(page=...)` picks
|
|
99
|
+
the page; without it the page whose regions cover the least area is used.
|
|
100
|
+
- `alpha_mode=` (`AlphaMode.STRAIGHT` / `AlphaMode.PREMULTIPLIED`, or the
|
|
101
|
+
strings) on `replace`, `replace_composite`, `add_region` and every extract
|
|
102
|
+
method: the image is converted to or from each page's own alpha space.
|
|
103
|
+
Without it nothing changes. On a pma page a straight extract drops additive
|
|
104
|
+
colour and is otherwise exact when replaced back with the same mode. A
|
|
105
|
+
composite group spanning pma and non-pma pages raises `MixedAlphaGroup` when
|
|
106
|
+
`alpha_mode` is given.
|
|
107
|
+
- Loading refuses an atlas that lists one page file twice (`DuplicatePage`),
|
|
108
|
+
as Spine does. Reading a region bigger than its page image raises
|
|
109
|
+
`ValueError` instead of allocating a padded crop of any size.
|
|
110
|
+
- Packed pages are capped at 10000 px per side: `CanvasTooLarge` is raised
|
|
111
|
+
before the page is allocated, with `.page` naming the page on a multi-page
|
|
112
|
+
atlas.
|
|
113
|
+
- The core package needs only Pillow, numpy and the `.skel` parser; the
|
|
114
|
+
desktop shell's dependencies moved to the `app` extra.
|
|
115
|
+
|
|
116
|
+
### Changed
|
|
117
|
+
- `"rectangles"` / `"polygons"` pages are trimmed to their regions' extent
|
|
118
|
+
(rounded up to a multiple of 4); nest growth used to leave part of its last
|
|
119
|
+
strip empty.
|
|
120
|
+
- The build cache keeps the last 8 packs of the current edits (within 512 MB
|
|
121
|
+
of edited page pixels) instead of one, so switching settings back is
|
|
122
|
+
instant. A pack that never used its padding (kept layout, no repack, no
|
|
123
|
+
addition) is reused for any padding. `"auto"` and the packer it resolves to
|
|
124
|
+
share one entry.
|
|
125
|
+
- A split composite on straight pages: each piece keeps the
|
|
126
|
+
composite's colour under its alpha-0 pixels instead of black, so the seam
|
|
127
|
+
between pieces filters cleanly where the piece is drawn in place.
|
|
128
|
+
- A page whose only edits are additions and renames is no longer repacked by
|
|
129
|
+
default (pass `PackOptions(try_keep_layout=False)`).
|
|
130
|
+
- Removing a region added in the same atlas undoes the add; a single-page
|
|
131
|
+
atlas used to repack every region.
|
|
132
|
+
- A single-page atlas with only renames keeps its image.
|
|
133
|
+
- Added regions with mesh data are cut to their hull when mesh-aware is on,
|
|
134
|
+
nest by hull under `polygons`, and stay mesh regions in the built atlas.
|
|
135
|
+
- Patch placement may store new regions rotated 180/270 under every packer,
|
|
136
|
+
shelf included, and may clear never-rendered pixels outside an existing mesh
|
|
137
|
+
hull where a new region lands.
|
|
138
|
+
- `build()` / `save()` take `options=PackOptions(...)` instead of `nest`,
|
|
139
|
+
`gap` and `mesh_aware`, which are removed.
|
|
140
|
+
- `padding` (formerly the Smart Packing gap) follows the Spine Texture Packer:
|
|
141
|
+
pixels between images, default 2 for every packer (the Smart Packing gap
|
|
142
|
+
was 4). The shelf packer now leaves this padding too; before, it packed
|
|
143
|
+
sprites edge to edge.
|
|
144
|
+
- `mesh_aware` defaults to on when the atlas has usable mesh data, and
|
|
145
|
+
`SpineAtlas.open()` reads a `.skel` next to the atlas. So a default
|
|
146
|
+
`build()` masks repacked pages to the mesh hulls, and
|
|
147
|
+
a split composite gives each meshed region its hull.
|
|
148
|
+
`PackOptions(mesh_aware=False)` turns the masking off (the shelf layout
|
|
149
|
+
still has at least 1 px padding; the old edge-to-edge layout is gone).
|
|
150
|
+
Untouched and rename-only pages keep their pixels.
|
|
151
|
+
- `packer="rectangles"` can be combined with `mesh_aware`: pixels are cut to
|
|
152
|
+
the hull, but the packing uses each region's whole rect.
|
|
153
|
+
- `pma: true` pages keep additive colour (RGB on alpha-0 pixels) through
|
|
154
|
+
every repack, extract and split. A composite whose regions all live on pma
|
|
155
|
+
pages round-trips exactly through `extract_composite` / `replace_composite`
|
|
156
|
+
/ a split `build()` when it is extracted with the same names in
|
|
157
|
+
the same order, no region is resized and `mesh_crop` matches the build's
|
|
158
|
+
ownership; additive colour goes to the topmost region
|
|
159
|
+
covering it. In a group that mixes pma and non-pma pages, the pma pieces
|
|
160
|
+
are cleared outside their owner and keep alpha-0 colour only where they
|
|
161
|
+
are the topmost owner. Forced Resizing on pma pages uses a premultiplied Lanczos that
|
|
162
|
+
scales a pixel down when its filtered alpha overshoots 255.
|
|
163
|
+
- `extract_composite` warns when its regions span pma and non-pma pages, as
|
|
164
|
+
`replace_composite` already did; such a composite is stacked as straight
|
|
165
|
+
alpha.
|
|
166
|
+
|
|
167
|
+
- Mesh Cropping previews and extracts are about 2-3x faster (vectorized mesh
|
|
168
|
+
masks, masking only the area a region covers), with the same pixels.
|
|
169
|
+
View Mode Extract and Save image write PNGs at compression level 3: about
|
|
170
|
+
1.7x faster, files about 10% larger. Saved atlases keep the default level.
|
|
171
|
+
- The web app stores its settings under new keys, so existing web users
|
|
172
|
+
start from the defaults once. The desktop app keeps `config.json`.
|
|
173
|
+
- The JS engine is gone from the tree (archived on `legacy/js-app`), and so
|
|
174
|
+
are the tests that compared the Python engine with it.
|
|
175
|
+
|
|
176
|
+
### Fixed
|
|
177
|
+
- `pma: true` pages: composite extracts and previews stack premultiplied
|
|
178
|
+
colour instead of treating it as straight alpha.
|
|
179
|
+
|
|
180
|
+
### Differences from the JS engine (0.4.x)
|
|
181
|
+
- Keeping a page's layout (adds go into free space), undo-on-remove and hull
|
|
182
|
+
cutting of added regions are Python-only; the app always repacks and keeps
|
|
183
|
+
added sprites whole.
|
|
184
|
+
- `pma` is kept on repack (the app drops it).
|
|
185
|
+
- pma pages are masked to mesh hulls, keep alpha-0 colour when deduplicating
|
|
186
|
+
sprites, and are resized with a premultiplied Lanczos (the app treats pma
|
|
187
|
+
pixels as straight alpha).
|
|
188
|
+
- Page lines other than the standard ones, such as `scale:`, are kept on
|
|
189
|
+
repack.
|
|
190
|
+
- Extracted file names keep non-ASCII letters (the app turns them into `_`).
|
|
191
|
+
- Output images carry no metadata such as embedded colour profiles.
|
|
192
|
+
- Repack deduplication also compares sprite sizes.
|
|
193
|
+
- Forced Resizing with Mesh Cropping resizes a region before masking it, so a
|
|
194
|
+
scaled composite round-trips exactly.
|
|
195
|
+
- Nest pages are trimmed to their regions (the app keeps the grown canvas).
|
|
196
|
+
- The shelf packer leaves padding between sprites (the app packs them edge to
|
|
197
|
+
edge), and nest packing defaults to 2 px padding (the app's gap is 4).
|
|
198
|
+
`"rectangles"` can be combined with mesh_aware (the app always nests
|
|
199
|
+
mesh-aware regions on their mesh).
|
|
200
|
+
|
|
201
|
+
## [0.4.2] - 2026-10-28
|
|
202
|
+
|
|
203
|
+
### Fixed
|
|
204
|
+
- Extracting several regions to a folder that already holds files with the same
|
|
205
|
+
names: the "Overwrite files?" dialog was covered by the Processing overlay and
|
|
206
|
+
could not be clicked. Only the extraction itself shows Processing now.
|
|
207
|
+
|
|
208
|
+
## [0.4.1] - 2026-10-12
|
|
209
|
+
|
|
210
|
+
### Fixed
|
|
211
|
+
- Saved `.atlas` files now end with a newline, like Spine's own exporter.
|
|
212
|
+
Without it, runtimes built on spine-cpp could read past the end of the file
|
|
213
|
+
text when loading an edited atlas.
|
|
214
|
+
|
|
215
|
+
## [0.4.0] - 2026-10-09
|
|
216
|
+
|
|
217
|
+
The desktop app and the web app now share one interface and one engine.
|
|
218
|
+
|
|
219
|
+
### Added
|
|
220
|
+
- **Mesh Cropping** (View mode): crop each region to its mesh silhouette from a
|
|
221
|
+
sibling `.skel`, so neighbouring pixels no longer leak into previews or
|
|
222
|
+
extracted sprites.
|
|
223
|
+
- **Mesh-Aware** (Edit mode): apply the same silhouette before repacking.
|
|
224
|
+
- **Show Mesh Silhouettes**: draw the selected regions' meshes over the preview
|
|
225
|
+
(preview-only).
|
|
226
|
+
- `.skel` picker next to the mesh toggles, with missing / invalid / ready
|
|
227
|
+
states; `.skel` files can also be dropped onto the window.
|
|
228
|
+
- **Forced Resizing** (View mode): stretch a selection to the largest region's
|
|
229
|
+
canvas and stack it in the preview.
|
|
230
|
+
- **Smart Packing** (Beta): silhouette-aware packing that fills gaps, with a
|
|
231
|
+
configurable gap (default 4 px). Saved atlases may contain `rotate: 180` and
|
|
232
|
+
`rotate: 270`.
|
|
233
|
+
- **Advance Mode** (Beta): Rename, Add and Remove regions on single-page atlases.
|
|
234
|
+
- **Copy .skel** option in the Save As menu (on by default).
|
|
235
|
+
- Confirmation before a save or extract replaces existing files.
|
|
236
|
+
|
|
237
|
+
### Changed
|
|
238
|
+
- Every edit repacks the page immediately; the Repack checkbox is gone. The
|
|
239
|
+
packer prefers near-square sheets.
|
|
240
|
+
- The desktop app now runs the same JavaScript engine and UI as the web app;
|
|
241
|
+
the Python side only handles native dialogs, file access and updates.
|
|
242
|
+
- Saving a preview image with no extension stores it as `.png`.
|
|
243
|
+
- The installer removes the old `ui` folder left by 0.3.x.
|
|
244
|
+
|
|
245
|
+
### Known issues
|
|
246
|
+
- Smart Packing with Mesh-Aware on very large atlases (for example 4096x4096
|
|
247
|
+
with hundreds of regions) can exceed the 5-minute packing limit and be
|
|
248
|
+
cancelled.
|
|
249
|
+
|
|
250
|
+
## [0.3.4] - 2026-07-15
|
|
251
|
+
|
|
252
|
+
### Fixed
|
|
253
|
+
- Repacking a single region modded with a full-canvas image of a different size
|
|
254
|
+
kept stale offsets, corrupting the extracted sprite. Offsets are now reset for
|
|
255
|
+
full-canvas mods regardless of how many regions are selected. Also fixed in
|
|
256
|
+
the web version.
|
|
257
|
+
|
|
258
|
+
## [0.3.3] - 2026-07-10
|
|
259
|
+
|
|
260
|
+
### Fixed
|
|
261
|
+
- Repacked and merged page PNGs are padded to multiple-of-4 dimensions for
|
|
262
|
+
GPU block compression (ASTC/ETC2/DXT); the `size:` line always matches the
|
|
263
|
+
saved PNG.
|
|
264
|
+
|
|
265
|
+
## [0.3.2] - 2026-07-03
|
|
266
|
+
|
|
267
|
+
### Fixed
|
|
268
|
+
- Right-click **Copy Image** on the preview, broken since the 0.3.0 UI split.
|
|
269
|
+
|
|
270
|
+
## [0.3.1] - 2026-06-28
|
|
271
|
+
|
|
272
|
+
### Fixed
|
|
273
|
+
- Reliable silent self-update for installed Windows builds: the installer runs
|
|
274
|
+
directly from the app, Mark-of-the-Web is removed from the downloaded
|
|
275
|
+
installer, `AppMutex` is dropped so `/FORCECLOSEAPPLICATIONS` can close the
|
|
276
|
+
app, command-line arguments are restored after the update, and the update
|
|
277
|
+
process is detached so the app can exit cleanly.
|
|
278
|
+
|
|
279
|
+
## [0.3.0] - 2026-06-28
|
|
280
|
+
|
|
281
|
+
### Added
|
|
282
|
+
- New UI with an app bar and separate View / Edit modes, Save Image, a
|
|
283
|
+
multi-page page switcher, a missing-page dialog and a preview cache.
|
|
284
|
+
- Multi-page atlas repack in modify mode.
|
|
285
|
+
- Windows installer (Inno Setup, per-user, no admin) with optional `.atlas`
|
|
286
|
+
file association, plus a portable zip.
|
|
287
|
+
- Installer-based silent self-update (portable builds link to the releases
|
|
288
|
+
page).
|
|
289
|
+
- `--debug` command-line flag.
|
|
290
|
+
|
|
291
|
+
### Changed
|
|
292
|
+
- Nuitka onedir build instead of a single bundled exe.
|
|
293
|
+
- Python code reorganised into the `atlas_toolkit` package.
|
|
294
|
+
- Atlas parsing and rendering fixes ported from the web version (offsets,
|
|
295
|
+
rotation, page detection).
|
|
296
|
+
|
|
297
|
+
### Migration
|
|
298
|
+
- Builds from 0.2.2 cannot self-update to the installer: download and run it
|
|
299
|
+
once.
|
|
300
|
+
|
|
301
|
+
## [0.2.2] - 2026-04-02
|
|
302
|
+
|
|
303
|
+
### Fixed
|
|
304
|
+
- Region names were sometimes misread as page images.
|
|
305
|
+
- Missing offsets when updating atlas text.
|
|
306
|
+
- Empty region selection in the modifier.
|
|
307
|
+
- Hardened update-notification rendering.
|
|
308
|
+
|
|
309
|
+
## [0.2.1] - 2026-02-26
|
|
310
|
+
|
|
311
|
+
### Fixed
|
|
312
|
+
- `rotate` was not written when the original region had no `rotate:` line but
|
|
313
|
+
the merged region needed rotation.
|
|
314
|
+
- Bounds were swapped after rotation; Spine bounds keep pre-rotation sizes.
|
|
315
|
+
|
|
316
|
+
## [0.2.0] - 2026-02-24
|
|
317
|
+
|
|
318
|
+
### Added
|
|
319
|
+
- LibGDX-to-Spine atlas format converter.
|
|
320
|
+
- Update check on startup with a notification bar.
|
|
321
|
+
- Repack preference saved between sessions.
|
|
322
|
+
- App version in the window title.
|
|
323
|
+
|
|
324
|
+
### Changed
|
|
325
|
+
- Executable signing in CI.
|
|
326
|
+
- Cleaner atlas text output matching the standard Spine format.
|
|
327
|
+
|
|
328
|
+
### Fixed
|
|
329
|
+
- Manual CI builds showed the branch name as the version.
|
|
330
|
+
|
|
331
|
+
## [0.1.2] - 2026-02-21
|
|
332
|
+
|
|
333
|
+
### Fixed
|
|
334
|
+
- Packaged build crashes: drag-and-drop setup, console output buffering and a
|
|
335
|
+
pywebview recursion issue under Nuitka.
|
|
336
|
+
- Multi-monitor window centring and header text wrapping.
|
|
337
|
+
- Release automation: tagging now triggers the build workflow.
|
|
338
|
+
|
|
339
|
+
[0.4.1]: https://github.com/com55/AtlasToolkit/compare/v0.4.0...v0.4.1
|
|
340
|
+
[0.4.0]: https://github.com/com55/AtlasToolkit/compare/v0.3.4...v0.4.0
|
|
341
|
+
[0.3.4]: https://github.com/com55/AtlasToolkit/compare/v0.3.3...v0.3.4
|
|
342
|
+
[0.3.3]: https://github.com/com55/AtlasToolkit/compare/v0.3.2...v0.3.3
|
|
343
|
+
[0.3.2]: https://github.com/com55/AtlasToolkit/compare/v0.3.1...v0.3.2
|
|
344
|
+
[0.3.1]: https://github.com/com55/AtlasToolkit/compare/v0.3.0...v0.3.1
|
|
345
|
+
[0.3.0]: https://github.com/com55/AtlasToolkit/compare/v0.2.2...v0.3.0
|
|
346
|
+
[0.2.2]: https://github.com/com55/AtlasToolkit/compare/v0.2.1...v0.2.2
|
|
347
|
+
[0.2.1]: https://github.com/com55/AtlasToolkit/compare/v0.2.0...v0.2.1
|
|
348
|
+
[0.2.0]: https://github.com/com55/AtlasToolkit/compare/v0.1.2...v0.2.0
|
|
349
|
+
[0.1.2]: https://github.com/com55/AtlasToolkit/compare/v0.1.1...v0.1.2
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# spine-atlas-toolkit
|
|
2
|
+
|
|
3
|
+
Read, extract, edit and repack [Spine](http://esotericsoftware.com/) texture
|
|
4
|
+
atlases (`.atlas` + page PNGs) from Python. This is the engine of the
|
|
5
|
+
[AtlasToolkit](https://github.com/com55/AtlasToolkit) web and desktop apps.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install spine-atlas-toolkit
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Python 3.11 or later. Dependencies: NumPy, Pillow and `skel-mesh-parser`.
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
import spine_atlas_toolkit as sat
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Open and extract
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
atlas = sat.SpineAtlas.open("hero.atlas") # loads the page PNGs, and hero.skel if present
|
|
23
|
+
|
|
24
|
+
for region in atlas.regions:
|
|
25
|
+
print(region.name, region.page, region.bounds)
|
|
26
|
+
|
|
27
|
+
atlas.extract("head").save("head.png") # a PIL image at the region's original size
|
|
28
|
+
atlas.extract_all_to("sprites/") # every region as a PNG
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Edit and save
|
|
32
|
+
|
|
33
|
+
Edits are recorded first; `save()` (or `build()`) packs them once.
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from PIL import Image
|
|
37
|
+
|
|
38
|
+
atlas.replace({"head": "new_head.png"}) # a path or a PIL image
|
|
39
|
+
atlas.add_region("hat", Image.open("hat.png"))
|
|
40
|
+
atlas.rename_region("arm", "left_arm")
|
|
41
|
+
atlas.remove_region("tail")
|
|
42
|
+
|
|
43
|
+
atlas.save("out/hero.atlas") # writes the .atlas and its page PNGs
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`build()` does the same in memory and returns a new `SpineAtlas`; the original
|
|
47
|
+
is unchanged. `SpineAtlas.load(text, {"hero.png": image, ...})` opens an atlas
|
|
48
|
+
from memory.
|
|
49
|
+
|
|
50
|
+
## Edit several regions as one picture
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
sheet = atlas.extract_composite(["head", "arm"], force_resize=True)
|
|
54
|
+
# ... edit `sheet` in an image editor ...
|
|
55
|
+
atlas.replace_composite(["head", "arm"], sheet)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
By default the edited picture is cut back into one piece per region.
|
|
59
|
+
|
|
60
|
+
## Pack options
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
atlas.save("out/hero.atlas", options=sat.PackOptions(packer="rectangles", padding=4))
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
| Option | Default | What it does |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| `packer` | `"auto"` | `"shelf"` (rows), `"rectangles"` (nests rects), `"polygons"` (nests by mesh outline; needs a `.skel`). `"auto"` is `"polygons"` with mesh data, else `"rectangles"`. |
|
|
69
|
+
| `padding` | `2` | Pixels between packed images (1–256). |
|
|
70
|
+
| `mesh_aware` | on with mesh data | Cut pixels outside each region's mesh before packing. |
|
|
71
|
+
| `try_keep_layout` | `True` | An edited page keeps its existing positions when the edit fits (same size, no new overlap; additions go into free space); otherwise it is repacked. `False` always repacks edited pages. |
|
|
72
|
+
| `bleed` | auto | Fill transparent pixels next to images with their colour (alpha stays 0), so filtering draws no dark edges. On when composites are split. |
|
|
73
|
+
| `share_composite_image` | `False` | For `replace_composite`: give every region the whole picture instead of cutting it into pieces. |
|
|
74
|
+
|
|
75
|
+
## Mesh data (`.skel`)
|
|
76
|
+
|
|
77
|
+
With a `.skel` next to the atlas (or passed to `load()`), these use the mesh
|
|
78
|
+
outlines:
|
|
79
|
+
|
|
80
|
+
- `extract(..., mesh_crop=True)` cuts pixels outside the region's mesh.
|
|
81
|
+
- `packer="polygons"` and `mesh_aware` (see above).
|
|
82
|
+
|
|
83
|
+
Without usable mesh data they raise `SkeletonUnavailable`.
|
|
84
|
+
|
|
85
|
+
## Premultiplied alpha
|
|
86
|
+
|
|
87
|
+
Pages marked `pma: true` are read and written premultiplied. For ordinary
|
|
88
|
+
(straight-alpha) PNGs, pass `alpha_mode="straight"` to `replace`,
|
|
89
|
+
`replace_composite`, `add_region` and the extract methods:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
atlas.replace({"head": "new_head.png"}, alpha_mode="straight")
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Multi-page atlases
|
|
96
|
+
|
|
97
|
+
Only the pages that own an edited region are repacked. `add_region(page=...)`
|
|
98
|
+
picks the page; otherwise the least-filled page is used.
|
|
99
|
+
|
|
100
|
+
## Errors
|
|
101
|
+
|
|
102
|
+
All errors derive from `sat.AtlasError`: `RegionNotFound`,
|
|
103
|
+
`DuplicateRegionName`, `InvalidRegionName`, `MissingPageImage`,
|
|
104
|
+
`SkeletonUnavailable`, `CanvasTooLarge` (a page over 10000 px; `.page` names
|
|
105
|
+
it), `MixedAlphaGroup` and `DuplicatePage`.
|
|
106
|
+
|
|
107
|
+
## API reference
|
|
108
|
+
|
|
109
|
+
Everything below is importable from `spine_atlas_toolkit`. Arguments after `*`
|
|
110
|
+
are keyword-only; `alpha_mode` is `None`, `"straight"` or `"premultiplied"`
|
|
111
|
+
(see [Premultiplied alpha](#premultiplied-alpha)).
|
|
112
|
+
|
|
113
|
+
### `SpineAtlas`
|
|
114
|
+
|
|
115
|
+
**Open**
|
|
116
|
+
|
|
117
|
+
| | |
|
|
118
|
+
|---|---|
|
|
119
|
+
| `SpineAtlas.open(atlas_path, *, images=None, skeleton=None)` | Open an `.atlas` file. Its page PNGs and a `.skel` with the same name are read from its folder unless given: `images` as `{page file name: image or path}` (or one image for a one-page atlas), `skeleton` as bytes or a path. |
|
|
120
|
+
| `SpineAtlas.load(atlas_text, pages, *, skeleton=None)` | Open from memory: the atlas text and `{page file name: PIL image or path}` (or one image for a one-page atlas). |
|
|
121
|
+
|
|
122
|
+
**Properties**
|
|
123
|
+
|
|
124
|
+
| | |
|
|
125
|
+
|---|---|
|
|
126
|
+
| `regions` | All regions, as `Region` objects. |
|
|
127
|
+
| `pages` | `{page file name: PIL image}`. |
|
|
128
|
+
| `atlas_text` | The `.atlas` text. |
|
|
129
|
+
| `has_changes` | `True` while there are edits not yet built. |
|
|
130
|
+
| `mesh_unavailable_reason` | `None` when mesh data is usable, otherwise why not. |
|
|
131
|
+
|
|
132
|
+
**Read**
|
|
133
|
+
|
|
134
|
+
| | |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `region(name)` | One `Region`. |
|
|
137
|
+
| `page_image(name)` | A copy of one page as loaded. |
|
|
138
|
+
| `page_is_pma(page)` | Whether a page is premultiplied (`pma: true`). |
|
|
139
|
+
|
|
140
|
+
**Extract**
|
|
141
|
+
|
|
142
|
+
| | |
|
|
143
|
+
|---|---|
|
|
144
|
+
| `extract(names, *, mesh_crop=False, alpha_mode=None)` | One name → a PIL image at the region's original size; a list → `{name: image}`. |
|
|
145
|
+
| `extract_all(*, mesh_crop=False, alpha_mode=None)` | `{name: image}` for every region. |
|
|
146
|
+
| `extract_to(names, path, *, mesh_crop=False, alpha_mode=None)` | Save as PNG: one name to the file `path`, a list into the folder `path`. |
|
|
147
|
+
| `extract_all_to(directory, *, mesh_crop=False, alpha_mode=None)` | Save every region as a PNG into `directory`. |
|
|
148
|
+
| `extract_composite(names, *, force_resize=False, mesh_crop=False, alpha_mode=None)` | Several regions stacked into one image; `force_resize` scales them to the largest one. |
|
|
149
|
+
| `extract_composite_to(names, path, *, force_resize=False, mesh_crop=False, alpha_mode=None)` | Save `extract_composite()` as a PNG. |
|
|
150
|
+
|
|
151
|
+
**Edit** (recorded until `build()` / `save()`)
|
|
152
|
+
|
|
153
|
+
| | |
|
|
154
|
+
|---|---|
|
|
155
|
+
| `replace(images, *, alpha_mode=None)` | `{name: image or path}`: new pixels for regions. |
|
|
156
|
+
| `replace_composite(names, image, *, alpha_mode=None)` | One image for several regions (the inverse of `extract_composite`). |
|
|
157
|
+
| `add_region(name, image, page=None, *, alpha_mode=None)` | Add a region; `page` picks the page, otherwise the least-filled one. |
|
|
158
|
+
| `rename_region(name, new_name)` | Rename a region. |
|
|
159
|
+
| `remove_region(names)` | Remove one region or a list. |
|
|
160
|
+
| `reset()` | Discard all recorded edits. |
|
|
161
|
+
| `set_skeleton(skeleton)` | Replace the mesh data (`.skel` bytes, or `None` to drop it) without discarding edits. |
|
|
162
|
+
|
|
163
|
+
**Pack and save**
|
|
164
|
+
|
|
165
|
+
| | |
|
|
166
|
+
|---|---|
|
|
167
|
+
| `build(*, options=None)` | Pack the edits and return a new `SpineAtlas`; this one is unchanged. |
|
|
168
|
+
| `save(atlas_path, *, options=None)` | `build()`, then write the `.atlas` and its page PNGs next to it. |
|
|
169
|
+
|
|
170
|
+
`options` is a `PackOptions` (see [Pack options](#pack-options)).
|
|
171
|
+
|
|
172
|
+
### `Region`
|
|
173
|
+
|
|
174
|
+
A frozen dataclass: `name`, `original_name` (the name in the loaded atlas;
|
|
175
|
+
`None` for an added region), `page`, `bounds` (`(x, y, w, h)` on the page),
|
|
176
|
+
`rotate` (0, 90, 180 or 270) and `offsets` (`(left, bottom, original_w,
|
|
177
|
+
original_h)` as in the atlas, or `None`), plus the properties `renamed` and
|
|
178
|
+
`added`.
|
|
179
|
+
|
|
180
|
+
### `PackOptions`, `Packer`, `AlphaMode`
|
|
181
|
+
|
|
182
|
+
- `PackOptions(*, packer="auto", padding=2, mesh_aware=None, try_keep_layout=True, bleed=None, share_composite_image=False)`
|
|
183
|
+
(`None` means automatic; see the table above).
|
|
184
|
+
- `Packer`: `AUTO`, `SHELF`, `RECTANGLES`, `POLYGONS` (or the same names as
|
|
185
|
+
lowercase strings).
|
|
186
|
+
- `AlphaMode`: `STRAIGHT`, `PREMULTIPLIED` (or `"straight"` / `"premultiplied"`).
|
|
187
|
+
|
|
188
|
+
### Exceptions
|
|
189
|
+
|
|
190
|
+
`AtlasError` is the base class of `RegionNotFound`, `DuplicateRegionName`,
|
|
191
|
+
`InvalidRegionName`, `MissingPageImage`, `SkeletonUnavailable`,
|
|
192
|
+
`CanvasTooLarge`, `MixedAlphaGroup` and `DuplicatePage`.
|
|
193
|
+
|
|
194
|
+
## More
|
|
195
|
+
|
|
196
|
+
- Changes: [CHANGELOG](https://github.com/com55/AtlasToolkit/blob/main/CHANGELOG.md)
|
|
197
|
+
- Source and issues: [github.com/com55/AtlasToolkit](https://github.com/com55/AtlasToolkit)
|
|
198
|
+
- License: Apache-2.0. Not affiliated with Esoteric Software (Spine).
|