pantin

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:

  1. Each pixel has a height from 0 to 1: its alpha, times 0.8 + 0.2 × luma, where luma is 0.2126 r + 0.7152 g + 0.0722 b of its colour from 0 to 1. The shape is raised, and a darker line of the drawing is a little lower.
  2. The heights are blurred three times by a box of 2 × softness + 1 pixels along the rows, then along the columns, softness taken to a whole number; beyond the image the height is 0. The edges are rounded over about softness pixels.
  3. At each pixel the slopes are the central differences, dx = (h(x + 1) − h(x − 1)) / 2 and dy = (h(y + 1) − h(y − 1)) / 2, rows counted downwards, and the normal is (−k dx, k dy, 1) made of length one, with k = 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.