This page is docs/format/atlas.md of the repository, as it is on main.
The pantin atlas format, version 0.4
An atlas is several images packed into a few, so that a game loads and draws a character from as few textures as it can. It is files side by side:
- one PNG image for each page, each holding some of the images;
- a JSON document, in UTF-8, whose name ends in
.atlas.json, that says on which page each image is, and where.
This page says what the JSON document means. The same structure is given to machines by the
JSON Schema beside it, pantin-atlas-0.4.schema.json.
The atlas format has version numbers of its own, apart from those of the skeleton format: one can change without the other. As there, a field the format does not know is refused, and so is a file in another version.
{
"format_version": "0.4",
"pages": [
{
"image": "atlas.png",
"width": 128,
"height": 128,
"regions": [
{ "name": "5HDTK114G4X3RSQVJ4FZD0FE1C", "x": 2, "y": 2, "width": 44, "height": 56 },
{ "name": "5Y2Q9DC9R4R372CK74WSKF8AZ6", "x": 50, "y": 2, "width": 38, "height": 30,
"rotated": true, "trim": { "width": 36, "height": 44, "x": 4, "y": 2 } }
]
},
{
"image": "atlas_2.png",
"width": 16,
"height": 16,
"regions": [
{ "name": "1NRNCS345SGC1SGCS1982XPA6M", "x": 2, "y": 2, "width": 12, "height": 12 }
]
}
]
}
The file
| Field | Meaning |
|---|---|
format_version |
"0.4". |
pages |
The pages, each one image. |
Pages
| Field | Meaning |
|---|---|
image |
The PNG file of the page, relative to the folder of the atlas file. No two pages have the same. |
width, height |
The size of that image, in pixels. |
regions |
The images that were packed on this page. |
Regions
| Field | Meaning |
|---|---|
name |
The image, as the skeleton names it. In a project, its identifier: the image that the attachments of rig.json give it, which is a key of [images] in pantin.toml. Moving or renaming the file of an image leaves the atlas good. In a file of the format before, which has no identifiers, the path that its attachments give it, exactly as it is written there. |
x, y |
The left and the top of the image on its page, in pixels from the left and from the top of the page. |
width, height |
The size of the region on the page, in pixels. |
rotated |
true when the image is on the page turned a quarter clockwise: its own width is the height of the region, and its own top is along the right of the region. Written only when it is true. Since 0.4. |
trim |
When the image was trimmed of the transparent pixels around it, the region holds the part that is left, and trim says what the whole image was: its width and height, and the x and y of the part kept in it, from its left and its top, the image standing as it was drawn (not turned). Written only for an image trimmed. Since 0.4. |
The pixels of the regions are those of the images as they were packed: at the scale the
project packs them at (scale of [pack]), which a reader has no need to know, since an image
is drawn over the size its attachment gives it whatever its number of pixels.
Every region is whole inside its page, no two regions of a page are over each other, and no two regions of the whole atlas have the same name: an image is on one page only. A file that says otherwise is refused.
Normal maps
Pantin Light (the Light workspace, pantin light) makes a normal map of each image of the atlas,
so that a game can light the character, and writes them as an atlas of their own, in the folder
normals of the project beside the folder atlas: an atlas file and one PNG for each page, with
the same names, the same sizes and the same regions as the atlas of the colours. A game reads
the colour and the normal of a pixel at the same place.
Each pixel of a map holds the normal of the surface there, x to the right, y up and z
towards the viewer, each from -1 to 1 written from 0 to 255 ((n + 1) / 2 × 255, the
convention of OpenGL, green up), and the alpha of the image. Where the image is transparent,
and between the images, the normal faces the viewer: (128, 128, 255), with an alpha of 0.
A map is made from its image alone, with the light settings of the project:
- Each pixel has a height from 0 to 1: its alpha, times
0.8 + 0.2 × luma, wherelumais0.2126 r + 0.7152 g + 0.0722 bof its colour from 0 to 1. The shape is raised, and a darker line of the drawing is a little lower. - The heights are blurred three times by a box of
2 × softness + 1pixels along the rows, then along the columns,softnesstaken to a whole number; beyond the image the height is 0. The edges are rounded over aboutsoftnesspixels. - At each pixel the slopes are the central differences,
dx = (h(x + 1) − h(x − 1)) / 2anddy = (h(y + 1) − h(y − 1)) / 2, rows counted downwards, and the normal is(−k dx, k dy, 1)made of length one, withk = 4 × strength × max(softness, 0.5), the softness as it is written.
From the versions before
The version 0.3 was this format with no rotated and no trim: every image whole and standing.
Its schema, pantin-atlas-0.3.schema.json, is still beside this
page; an atlas of 0.3 is read as it is, and one that says rotated or trim is refused.
The version 0.2 had the same fields, and named every image by its path, a project too:
moving the file of an image made the atlas wrong for it. Its schema,
pantin-atlas-0.2.schema.json, is still beside this page. An
atlas of 0.2 is read with the names it has, and written as 0.4; to have the identifiers, pack
the project again.
The version 0.1 had one page, whose image, width, height and regions were fields of
the file itself. Its schema, pantin-atlas-0.1.schema.json, is
still beside this page. An atlas of 0.1 is read as an atlas of one page, with the names it
has, and written as 0.4.
Using an atlas
A skeleton names its images, and does not know whether they are separate files or parts of an
atlas: a project by their identifiers, a file of the format before by their path. To draw an
attachment from an atlas, look that name up among the names of the regions of every page. For a
region neither turned nor trimmed, the pixel (px, py) of the image is the pixel
(x + px, y + py) of the image of its page.
A region turned or trimmed is simplest cut out once, when the atlas is read: take the rectangle of
the region, turn it a quarter counter-clockwise when it is rotated, and, when it has a trim,
put it at (trim.x, trim.y) on a transparent image of trim.width by trim.height. That is the
image as it was drawn (pantin_bundle::cut_out does it). The Bevy and the Godot runtimes do so;
a runtime that draws from the page instead finds the pixel (px, py) of the kept part at
(x + px, y + py), or turned, at (x + width − 1 − py, y + px).
A normal map of Pantin Light that is turned with its region has its directions turned too: what faced right in the image faces down on the page. Turned back, a map is the one of its image.
For a mesh, whose vertices have u and v from 0 to 1 over their image, the place in the
page of a region neither turned nor trimmed, from 0 to 1 over the page, is
U = (x + u · width) / page width
V = (y + v · height) / page height
What the editor writes
The Pack workspace, File › Export › Atlas… and pantin pack pack every image that the project
shows but those its settings ([pack] of pantin.toml) leave out, each one
once, named by its identifier (a file of the format before, by its path), on pages of at most 4096 pixels a side (pantin pack --page chooses another size; one
that is not a power of two is taken down to the one under it). The images go in rows, the
tallest first, as many as a page holds, and those that do not fit go on the next page; an
image larger than a page is refused, with its name and its size. Each page has sides that are
powers of two and is never taller than it is wide. The first page is named after the atlas,
atlas.png, and the next ones with their number, atlas_2.png; pantin pack writes
atlas/atlas.atlas.json in the folder of the project unless it is told where. Around each image two
transparent pixels are left, so that a neighbour does not show at its edge when the atlas is
drawn scaled; the regions do not include them. The same images always give the same atlas.
The settings of [pack] may ask for more (since the project format 0.28): trim takes off the
transparent border of each image (an image with no transparent border, or one with no opaque
pixel, which keeps one, is whole); rotate turns an image a quarter clockwise when that takes
less room (in rows, an image taller than it is wide lies down); scale, from 1 to 100, packs
every image at that share of its pixels, its colours mixed with their alpha so that no dark
fringe comes; tight packs by free rectangles, the largest image first, each where it leaves
the least room, on the smallest page that holds them all; and per_skin writes beside the atlas
of all the images one atlas of the images of each skin, atlas_<skin>.atlas.json.