# Opening, importing and exporting Open sprites and images, turn pictures into pixel art, cut up sprite sheets, and export images, animations, sheets, video and timelapses. _Shortcuts are written for Windows and Linux. On a Mac, use ⌘ Cmd where they say Ctrl, and ⌥ Option for Alt._ pxstud.io keeps your work in the browser as you go ([Your first sprite](https://pxstud.io/docs/manual/start/first-sprite.md#saving)). This page covers getting files in and out. Which formats can do what is in [File formats](https://pxstud.io/docs/manual/reference/file-formats.md). ## Opening files File > Open... (`Ctrl+O`) opens a `.pxstudio` or Aseprite file, a file from another editor (Photoshop `.psd`, OpenRaster `.ora`, Piskel, Pixilart, Pixelorama, Pyxel Edit), or an image (PNG or animated PNG, GIF, JPEG, WebP, AVIF, BMP, TGA, PCX, QOI, ICO, CUR, Netpbm, FLI/FLC), as a new sprite in the current project, named after the file. You can also **drop** files onto the editor: - Several images at once ask whether to open them as **separate sprites** or as **one animation** (one frame per image, in file-name order). - A large image (over 512 pixels on a side) asks whether to **import it as pixel art** or open it as it is. - Other pictures the browser can show (SVG and so on) go to Import as pixel art. When something in a file can't be kept, a notice says what, for example an Aseprite file's color profile, a blend mode pxstud.io doesn't have, or a Photoshop adjustment layer. What each editor's files keep is in [File formats](https://pxstud.io/docs/manual/reference/file-formats.md). File > Save As... (`Ctrl+Shift+S`) downloads the sprite as a `.pxstudio` file, which keeps everything and opens again exactly as it was. ## Import ### Image as pixel art File > Import > Import image as pixel art... turns a photo or drawing into pixel art. 1. **Choose image...** or drop one in. (Pictures larger than 4096 pixels are shrunk first.) 2. Set the **size**: width and height, or a long side of 16, 32, 64 or 128. 3. Pick an **algorithm**: - **Balanced (SLIC + k-means)**, the default, groups pixels into regions of similar color; - **Smooth with outlines (bilateral)** smooths areas and can darken the edges between them; - **Crisp shapes (Kopf-Lischinski)** keeps sharp shapes and outlines. 4. Pick a **palette**: **Auto** finds the best colors (2 to 64 of them), or use the sprite's palette, one of My Palettes or a built-in palette. 5. Press **Start** to see the result, adjust, and press **Start again** to update it. 6. **Import as** a new sprite, or as a new layer in the current sprite (centered), and click **Import**. **Add the palette colors to the sprite palette** keeps the colors handy for touch-ups. ### Image sequence File > Import > Image sequence... picks several images and makes one sprite with a frame per image, in natural file-name order (`run2` before `run10`). The sprite is named after the first file without its number. Images of different sizes sit at the top-left of the largest. ### Sprite sheet File > Import > Sprite sheet... cuts a sheet into frames. Choose an image, or **Use current sprite**. - **Auto-detect grid** looks for the empty gaps between frames (transparent, or the sheet's background color) and sets the type, frame size, offset and padding to match. It runs when you choose an image, and again whenever you press it. It needs gaps between the frames, so a sheet whose frames touch keeps your settings and says so. - **Find frames by** **Detecting each sprite** is for sheets that aren't on a grid. See [Detecting sprites](https://pxstud.io/docs/manual/guides/import-export.md#detecting-sprites) below. - **Type:** Horizontal strip, Vertical strip, By rows or By columns. - **Frame W** and **Frame H**, **Offset**, **Padding**, and whether to include partial cells and skip empty ones. A grid over the sheet shows where the cuts fall. - **Aseprite JSON...** reads the frames, durations and tags from the JSON file Aseprite exports with a sheet, instead of the grid. Trimmed frames go back to their place on the full canvas, and Aseprite's inner padding is left out of each frame. - **Create** a new sprite, or **replace the current sprite's frames** (one undo step). #### Detecting sprites For packed or unevenly spaced sheets, choose **Detecting each sprite**. Each cluster of non-background pixels becomes one frame, shown as a numbered box over the sheet. - **Background:** Automatic uses transparency if the sheet has any, otherwise its most common color. Or choose Transparent, or a color. - **Tolerance** (0 to 255): how far from the background a pixel may be and still count as empty. Raise it to ignore faint noise or JPEG fuzz. - **Merge gap:** boxes with at most this many empty pixels between them join into one sprite, so a detached sword or spark stays with its character. 0 joins only boxes that overlap. - **Min pixels:** sprites with fewer pixels than this are dropped as specks. - **Joined:** whether pixels touching only at a corner belong to the same sprite. - **Order:** frames run row by row or column by column. - **Frame size** is the largest sprite's size, or a custom size (larger sprites are clipped). The **Anchor** decides where each sprite sits on that canvas: bottom center keeps feet on one line, which keeps a walk cycle from jittering. To correct the result by hand, click a box to select it. You can change its X, Y, W and H, shift where it sits on the frame (**Shift X** and **Shift Y**), move it **Earlier** or **Later** in the order, step to the **Previous** or **Next** box, or **Delete** it. Drag on an empty part of the sheet to draw a new box, which is added last. Changing a detection setting or pressing **Re-detect** runs detection again and discards these edits. Sprites that touch can't be told apart and come out as one box; split them by hand, or use the grid instead. ## Export File > Export... (`Ctrl+Alt+Shift+S`) opens one dialog for every format, with a preview of the real file. Hidden layers, reference layers and [draft layers](https://pxstud.io/docs/manual/guides/layers.md#draft-layers) are never exported (an Aseprite file keeps every layer). **For every type:** - **Resize (%)** scales by whole steps, 100% to 1600%, so pixels stay sharp squares. - **Apply pixel ratio** stretches non-square pixels to their shape. - **Frames:** all, the active frame, or one tag's frames. **Animation Direction:** forward, backward or ping-pong (for a tag, forward keeps the tag's own direction). - **Play subtags & repetitions** (when the sprite has tags, on by default as in Aseprite): the frames are exported the way playback plays them, through every tag in its direction, nested tags and repeat counts included, so a frame can appear more than once. Turn it off to export each frame once, in order (one file per frame for a PNG sequence). - **Area** (when the sprite has [slices](https://pxstud.io/docs/manual/guides/slices.md)): the whole canvas, one slice, or **Each slice**, which writes one export per slice. A slice that moves or resizes between frames exports at the box that covers it on every exported frame, so all its frames are the same size. With each slice, `{slice}` in the filename becomes the slice name (`{slice}.png` gives `head.png`); without it the name goes before the extension (`sprite-head.png`, `walk-head001.png`). Not for sprite sheets or the whole-file types. - **Filename.** For a PNG sequence, a number in the name sets the numbering: `walk001.png` gives `walk001.png`, `walk002.png` and so on; without one, frames are numbered `sprite-001.png`. **Per type:** | Type | Options | | - | - | | **PNG** | One image, or one per frame. | | **Animated GIF** | **Loop count** (0 loops forever, or uses the tag's repeat). **Dithering**: a GIF holds 256 colors, so an animation with more gets a palette picked from all its frames, and this chooses how the in-between colors are drawn (the same choices as [converting to indexed](https://pxstud.io/docs/manual/guides/color.md#color-modes); ordered patterns don't flicker between frames). Pixels under half opacity become transparent; GIF stores durations in 10 ms steps, 20 ms at least. | | **Animated PNG (APNG)** | **Loop count**. Keeps every color, soft transparency and exact durations; saved as `.png`. Apps without APNG support show the first frame. | | **WebP** | Still or animated; **Lossless**, or a **Quality** from 0 to 100; loop count. | | **Sprite Sheet** | Below. | | **Aseprite file** | The whole sprite, with layers, groups, linked cels, tags, slices and tilemaps. Group opacity and blend modes show in Aseprite with **Experimental > Compose groups** on. | | **Photoshop file (PSD)** | The active frame with its layers, groups, blend modes, opacity, visibility and clipping, plus the merged image. Opens in Photoshop, Krita, GIMP and Photopea. | | **OpenRaster (ORA)** | The active frame with its layers and groups, for Krita, GIMP, MyPaint and Pixelorama. | | **Piskel file** | Every frame and visible layer. Groups are flattened, and the file gets one frame rate (from the most common duration). | | **Tilemap (JSON / Tiled)** | Tileset images plus a Tiled map or a JSON file ([Tilemaps](https://pxstud.io/docs/manual/guides/tilemaps.md#exporting)). | | **MP4 video** | **Frame rate** (Auto keeps every duration exact), how many times it **plays**, and a **background color** (video has no transparency). Only offered where the browser can make video. | | **WebM video (VP9)** | How many times it **plays** and a **background color** (video has no transparency). Keeps every frame's exact duration. Only offered where the browser can make video. | | **FLC** | Autodesk Animator's format: up to 256 colors, transparency becomes black. | | **JPEG** | **Quality** and a **background color**. | | **AVIF** | **Quality**: 100 (the default) is lossless; lower makes a smaller file that isn't pixel-exact. | | **ICO, CUR** | Windows icons and cursors, up to 256×256. **All sizes** also stores each larger whole-number size up to 256 (a 32×32 sprite gives 32, 64, 96 … 256), so Windows picks a sharp one. A cursor's click point is the pivot of a slice named `hotspot`. | | **ANI** | An animated Windows cursor, up to 256×256. Every selected frame becomes one cursor image shown for the frame's duration (rounded to 1/60 s); repeated frames (ping-pong) are stored once. Set the click point with **Hotspot X / Y** (it starts at the `hotspot` slice pivot). | | **Crafts PDF** | A printable cross-stitch, bead or perler pattern of the current frame: a cover with a preview and the color count, the chart split into gridded pages, and a legend listing each color's symbol, swatch, hex, palette-group name and stitch count. Set the **cell size** (mm), **page size** (A4 or Letter), a heavier **grid line every** N cells, and **symbols** or **color fills**. Transparent cells are skipped; symbols mode takes up to 56 colors. | | **Netpbm** | Uncompressed `.pgm` (opaque grayscale), `.ppm` (opaque color) or `.pam` (with transparency); the extension follows the image. | | **TIFF** | Lossless, LZW-compressed. Indexed sprites keep their palette (unless they use their transparent color); other sprites save RGB, or RGBA when anything is transparent. One file per frame. | | **JPEG XL** | Lossless, with transparency. Limited to 1024×1024 pixels, so lower the resize for big exports. One file per frame. | | **BMP, TGA, PCX, QOI, SVG** | One file per frame. SVG draws each run of same-colored pixels as a rectangle. | ### Presets and queue **Presets and queue**, at the bottom of the Export dialog, saves and batches exports. Nothing in it asks for confirmation. - **Presets** keep the type and every option on that tab (resize, frames, area, filename, and the per-type options such as quality, background, hotspot, cell size or the sprite sheet settings) under a name you choose. **Save preset** with an existing name replaces it. **Apply** fills the dialog with a preset, and **Rename** and **Delete** do what they say. Presets stay on this device and need no account. A preset's tag, slice or frame choice that the current sprite doesn't have falls back to all frames or the whole canvas. - **Queue:** **Add current to queue** (or a preset's **Add to queue**) lines up an export with the settings as they are now. **Run queue** makes every file in one go: one download, or a single `pxstudio-export.zip` when the items make several files. Each item shows Waiting, Done or the error that stopped it; a failed item doesn't stop the others, and **Run queue** again retries the failed ones. **Remove** takes an item out. The queue is for the sprite and dialog you have open, and is empty again when the dialog closes. ### Sprite sheets The **Sprite Sheet** type has four tabs, laid out like Aseprite's: - **Layout:** strip, rows, columns or **Packed**; a fixed number of columns or rows, or a fixed width or height; best fit; merge duplicate frames; ignore empty ones. - **Sprite:** which layers and frames, whether to split layers or tags, and trimming. - **Borders:** border, spacing and inner padding, and **Extrude** (repeats edge pixels, to stop seams in games). - **Output:** an **Engine Preset**, the **Data File** (Aseprite JSON as a Hash or an Array, or a Godot 4 SpriteFrames `.tres`) and, for JSON, how each frame is named. The layouts work like Aseprite's, so the same options give the same sheet: - Strips, rows and columns place each frame at its own size, so trimmed frames don't take the space of the largest one. With no constraint, **By rows** and **By columns** make a near-square grid. - **Split Layers** puts each layer's frames one after the other, and **Split Tags** each tag's. **By rows** starts a new row for each layer and tag (**By columns**, a new column), unless a fixed width (height) wraps them. - **Packed** fits the frames, largest first, into the smallest sheet it can, close to square (100 trimmed frames of 4 to 43 px give 258×236 px, as in Aseprite). **Best fit: Smallest area** tries a few more sizes, and **Smallest power of two** gives a power-of-two sheet. - A fixed width or height is the sheet's width or height, even when the frames use less. - The preview warns when the sheet is over 16384 px on a side, which many GPUs and engines can't load. Trimming: - **Trim Sprite** crops every frame to the area any frame uses. **Trim Cels** crops each frame to its own content. With a visible Background layer, both trim away the background color (the color of the top-left pixel) instead of transparency. - **Trim by Grid** grows the trimmed area out to the grid lines, for either kind of trim. - The JSON keeps the frames in canvas coordinates: `sourceSize` is the canvas size and `spriteSourceSize` is where the frame's pixels sit on it, so engines and re-imports keep each frame in place. Frame names: leave **Item Filename** empty for Aseprite's names, `{title} {frame}.{extension}`, with ` ({layer})` added for one layer and ` #{tag}` for one tag (`hero (Body) #walk 0.aseprite`). `{frame}` counts from 0 for each layer and tag. The tokens are Aseprite's: | Token | Becomes | | - | - | | `{title}`, `{extension}`, `{name}` | The file name without its extension, the extension (`aseprite`), and both. | | `{layer}`, `{group}` | The layer, when the frames come from one layer, and its group. | | `{tag}`, `{innertag}`, `{outertag}` | The exported tag, or the shortest tag holding the frame; `{outertag}` is the longest. | | `{frame}`, `{tagframe}` | The frame number, and its number inside the tag. Digits set the start and width: `{frame1}` counts 1, 2, …; `{frame001}` gives 001, 002, …. | | `{duration}` | The frame's duration in milliseconds. | You get the sheet's PNG and a data file with the same name. The JSON lists each frame's position and duration, the tags, the exported layers and the slices, and is readable by game engines and tools that read Aseprite's JSON. Unlike Aseprite, a frame's `frame` rectangle doesn't include the inner padding, and tag ranges count the frames in the sheet. As in Aseprite, a tag's frames are in timeline order on the sheet, and its direction and repeat count are in the JSON for the game engine to apply. **Engine presets** set the layout for a game engine in one click: **Godot 4** and **Phaser / PixiJS** pack the frames, trim each one to its content, merge duplicates and add 1 px of extrude, so frames don't pick up their neighbors' edges when the camera moves or the texture is filtered. Godot 4 also picks the `.tres` data file. **Aseprite defaults** puts the layout back to a plain strip. You can change any option afterwards. #### Godot 4 With the **Godot 4 SpriteFrames (.tres)** data file: - Each tag becomes an animation with the tag's name. A sprite without tags gets one animation called `default`. With **Split Layers**, animations are named `layer/tag`. - Frame durations carry over exactly: the animation's speed comes from its most common frame duration, and longer or shorter frames get a matching relative duration. - Godot has no reverse, ping-pong or repeat setting, so the frames are written out in play order. A tag with a repeat count plays that many times (each way of a ping-pong counts once) and doesn't loop; other tags loop. - Trimmed frames keep their full size and position, so the sprite doesn't jump between frames. Put the PNG and the `.tres` in the same folder of your Godot project, then pick the `.tres` as the **Sprite Frames** of an **AnimatedSprite2D**. For crisp pixels, set **Project Settings > Rendering > Textures > Default Texture Filter** to **Nearest**. ## Export Timelapse File > Export Timelapse... makes a short GIF or MP4 of your sprite being drawn, for sharing. - **Animate:** **Draw in the finished sprite** (pixels appear in an order you choose: a scan, random dissolve, diagonal sweep, spiral, from the center, or color by color), or **Replay my edits** (your actual undo history from this session, stroke by stroke: the steps that led to where you are now, without undone steps or other branches). Pick a range of edits (**From edit** / **To edit**) and **Show every** Nth edit to speed up long builds. - With several layers or frames, choose whether they're drawn together or one at a time. - **Timing:** drawing time, frame rate, pace (ease in and out, steady, speed up, slow down), a pause between frames, a hold at the end, and how many times the finished animation then plays. - **Output:** GIF or MP4, scale (it aims for 1080 pixels by default), margin, a square canvas, and the background color (or transparent, for GIF).