Paint

Artworks and the canvas

A Paint document is an artwork. Everything in it, from pixel layers to shapes, text and frames, is listed in the Contents panel.

Colour space

An artwork is in Display P3, which reaches brighter, more saturated colours, or in sRGB. A new artwork starts in P3 if your screen can show it, and in sRGB if it can't. Switch an artwork's colour space in Settings, and new artworks start in that one from then on. Colours are picked in OKLCH in a P3 artwork, and in HSL in an sRGB one.

If you open a P3 artwork on a screen that can't show P3, and some of its colours are outside sRGB, a message says how many. Those colours are drawn clipped on that screen and kept as they are.

The colour pickers stop at the edge of Display P3, so a colour you pick is one a P3 screen can show. A swatch beyond it, from an older artwork, is marked in the Palette panel, and Bring ... into P3 there stores each one as the clipped colour it is already drawn in, so nothing visibly changes.

HDR

A P3 artwork can be HDR: turn on Use HDR in Settings. Each swatch's editor then has an HDR field: how far past white the swatch goes on an HDR screen, in stops, each a doubling of brightness. It goes up to the artwork's HDR range in Settings (+3 stops by default, +1 to +4). Double-click the field to set it back to 0. Background, foreground and accent take no gain, since the interface is drawn in them. Showing HDR needs a browser with WebGPU and an HDR screen; elsewhere the gains are kept and the colours stop at white.

The HDR button left of the current colours at the top right steps through how this view shows the gains, and HDR view in Settings does the same: Off shows every swatch at its base colour; Mapped (the default where HDR reaches the screen; elsewhere it starts Off) scales each gain down by the share of the range the screen can show, so the artwork keeps its shape on a dimmer HDR screen; Clamped shows the gains as set, and a screen with less headroom clips the brightest flat. The button says what the screen makes of it, such as "Mapped to +1", or "HDR unavailable" where nothing past white reaches the screen. It's remembered per artwork and isn't part of it. Mapping needs to know how far past white the screen goes, its headroom, which is set up in the Screens tab of Settings: read live in Chrome with Experimental Web Platform features on and screen access allowed (Detect automatically turns that off), or set for each screen by hand, or measured on a ramp of whites by clicking the first step that looks as bright as the brightest. Screens set by hand are kept with your account's settings, so they're known in every browser you sign in to. A headroom set by hand is right at the brightness it was set at, since macOS gives HDR less room the brighter the screen. HDR tends to look most natural with the screen at about two-thirds of its maximum brightness. Until it's known, the button reads "Mapped, screen unknown" and the gains show as set. While the Screens tab is open, the interface's shader effects are off. The first time an HDR artwork opens, the HDR setup wizard walks through all of this: it checks what your browser and screen can show, then goes through screen access, the experimental flag and measuring the screen, saying which are done already, and ends on a test card shown as Off, Mapped and Clamped, with two questions that tell whether the setup is right. Open it again from the HDR section of the artwork's settings or from Screens in Settings. An artwork turned HDR from SDR takes this screen's headroom as its HDR range.

Exports are SDR, each swatch at its base colour, unless an AVIF asks for HDR (see Exporting).

Artwork setup

Artwork setup holds the facts about the artwork itself. Name and Slug: the slug, the artwork's address, follows the name until you type your own, and Match name links it back. Date of work records when it was made or finished, separately from when the file was created: a year, a month or a day, as much as you know. The artwork's card on the Paint index shows it, as "July 2015", in place of when it was last edited. Notes is plain text for anything you want to keep with the artwork; an import writes what it couldn't bring across there. At the bottom, Record shows when the artwork was created and last updated, its version and its id. With nothing selected, Properties has a button that opens it. The pin in Properties' title bar opens a second panel held to what's selected: it shows that item's name, keeps editing it whatever you select next, and stays open until you unpin it.

To start another artwork set up the same way, right-click an artwork on the Paint page and choose New artwork with same setup. It takes the palettes with their swatches and halftone screens, the styles, the colour space and HDR settings, the effects and the clock, and none of the layers or artboards.

Importing files

Drop files anywhere on the Artworks page, or choose Import..., to turn them into new artworks: Photoshop (PSD and PSB), PNG, JPEG, GIF, WebP, AVIF, BMP, ICO, Aseprite and SVG files, and Pteropixel documents. Each one stays on this device until you save it. A Photoshop file's canvas becomes an artboard the size of the picture, and the artwork's cover, since its layers can run past it; anything else comes in as it is, without one.

Before anything is imported, the import dialog reads each file and shows what it is, its size, and a preview of the artwork it will become, drawn as Paint will draw it. A Photoshop file saved with Maximize Compatibility carries a flattened picture of itself, and the preview compares against it: with Hold to compare, press and hold the preview to see the original in its place; with Side by side, the original and the import are shown next to each other. The line under it says how many pixels look different. The preview opens fitted to the dialog: hold ⌘ and scroll, or pinch, to zoom in on the point under the pointer, up to 20×; drag to move around, and scroll once zoomed in. The buttons beside it zoom by whole steps, and the zoom level between them fits the picture again. A file with a timeline (an animated GIF, an Aseprite file, a Photoshop timeline brought in as sprites) plays in the preview, with a button after the frame count to pause it. A file that can't be imported says why there, and is left out. Where a file leaves a choice, the dialog offers it, set to what the file suggests, and the preview follows each change: whether an image comes in as pixels or as an image, whether pixel art saved at a larger size is scaled back down, how a layered file's Colours come in (with Swatches, Simplify colours merges rarely used swatches into close ones, with the same Tolerance, At most and Method settings as the palette's Simplify, dithering included), whether hidden layers are left out, how adjustment layers come in, whether a Photoshop timeline comes in as sprites, which of a Photoshop file's dates becomes the date of work, and whether an Aseprite palette's unused colours are kept. Every file also offers a Colour space: an imported artwork is an sRGB artwork by default, as the file is, or a Display P3 one, for colours beyond sRGB later; a P3 import's blend modes still work on the file's sRGB values, so it looks as it did. These choices are remembered for the next import. Choose Import to go ahead: import one file and it opens; import several and they appear on the index.

Anything that didn't come across as it was is listed in the dialog, and kept in the artwork's Notes in Artwork setup, which opens with the artwork after a single import so you can check it.

Colours has three settings. Automatic links each pixel layer's colours to swatches when the file uses 256 colours or fewer, and brings them in as free colours when it uses more, as a painting does; either way a layer too rich in colour for a palette, such as a photograph, comes in as an image fill. Swatches does the same and turns on the artwork's Always use swatches. Free colours keeps pixel layers' colours exact, without swatches; only the background, foreground and accent are swatches. The dialog lists the swatches each file will bring, with similar shades grouped as they will be in the palette, and says how many colours come in free. A large group of shades is split by the layers its colours belong to, so a sky's light blues and an ocean's dark ones land in groups of their own, named after the layer; colours shared between layers stay together. You can change your mind later with Convert to swatches and Convert to free colours (see Colour).

A photograph, or anything saved as JPEG, AVIF or lossy WebP, comes in as an image fill that keeps its own colours. Compression blurs a picture's colours into hundreds of near-duplicates, so they aren't turned into swatches. A PNG, GIF, BMP, ICO or lossless WebP is looked at first. If it has a manageable number of colours, each used many times, the dialog suggests a pixel layer with its colours as swatches; if it has many colours, or a long tail of colours used by only a pixel or two (smoothed edges, gradients), it suggests an image fill. Either can be chosen instead. Pixel art saved at 2×, 3× or larger is brought back to its own size unless you untick Scale down. Either way the background, foreground and accent colours are chosen from the picture.

An animated GIF or PNG comes in as a sprite that plays its sprite frames at their own speeds, each distinct one built as a frame to the right of the picture. A sprite frame shorter than 20 ms plays at 100 ms, as it does in browsers.

An Aseprite file keeps its layers and groups, their names, visibility, opacity, blend modes and locks, and its palette order, with every colour it uses as a swatch. Tick Keep the palette's unused colours as swatches to bring in the rest of its palette too; the choice is remembered for the next Aseprite file. A layer that stays the same in every frame comes in as a pixel layer; one that changes becomes a sprite. A file with tags comes in as a sprite per tag, each playing its tag's frames in its direction, side by side; the import dialog's preview shows a thumbnail per tag to pick which one plays; frames outside every tag are left out, and a tag that repeats a set number of times plays once. Untick Bring in the tags as separate sprites to play every frame in order instead. Addition comes in as Linear Dodge (Add). Not supported yet: tilemap layers and reference layers, which are left out.

An SVG drawn on a pixel grid, such as one exported from Paint or a pixel tool's grid of squares, comes back as a pixel layer with its pixels exactly as they were. Any other SVG comes in as vector shapes in its own groups, drawn on the pixel grid and editable as paths. Gradients come in as a single colour. Not supported yet: text, embedded images, clipping paths, masks and filters, which are left out. Nothing an SVG links to outside itself is loaded, and scripts in it never run.

A Pteropixel document (a .pteropixel.zip file) is a whole artwork with its images. Make one with Download document in the editor's save menu; it includes changes you haven't saved. Importing one makes a new artwork, however many times you import it, and leaves the one it came from alone. It also carries a small picture of the artwork, preview.png, for anything that wants to show the file without opening it. Fonts aren't included: text keeps its font by name, and uses a fallback on an account that doesn't have it.

Every file is checked before it's read. A file that is too large (over 80 megapixels, or an animation too long to hold), or whose contents aren't one of these formats whatever its name, is refused. An image fill is uploaded with the artwork when you first save, and one upload carries at most 4.4 MB: a photograph keeps its own file to stay small, and the dialog says when an image would still be too large. Bringing it in as pixels instead may fit.

Files opens on the artwork's own folder. Files dropped onto it, or added with Add files..., are kept with the artwork, with a note of where each came from; the files Pteropixel keeps for the artwork are listed below them, under Managed by Pteropixel, and can't be changed there. Double-click an added file to rename it. Open shows a note or a JSON file in a window of its own, where an added one is edited; it saves when you click away. Drag a picture from it onto the canvas to place it as a linked image: the artwork keeps only its address, not a copy.

From Photoshop

A Photoshop file's layers and groups keep their order, names, visibility, opacity and blend mode, and the canvas becomes an artboard. A layer with Lock All (or its pixels and position both locked) comes in locked; a lock on one alone isn't kept. Its colours come in as the dialog's Colours setting says. A file saved in another colour space, such as Adobe RGB (1998), has its colours converted to sRGB, as Photoshop shows them; the import notes say how many were outside sRGB and came in as the nearest it has. With free colours, every layer comes in as a pixel layer, however many colours it has. With swatches, a layer whose colours make a picture rather than a palette, such as a photograph or a smoothly resized drawing, comes in as an image fill that keeps its own colours; it stays on this device with the artwork and is uploaded when you first save. The background, foreground and accent colours are chosen from the picture's largest and most prominent areas, as swatches of their own, each moved a little lighter or darker until it visibly differs from the art's colours and from the other two, so changing one doesn't recolour the art. If the file records when it was created in Photoshop, that becomes the artwork's date of work, and the import notes say so. When it also records a later last save, the dialog's Date of work chooses between the two.

Text, shape, fill and smart-object layers come in as pixels, and a Color Overlay effect is drawn into its layer's pixels. Adjustment layers come in one of two ways, as the dialog's Adjustment layers setting says. Works as it did, the default, brings each one in as an adjustment, with its opacity, blend mode, clipping and mask, over the layers as they were painted, so it can be edited as it was built. Looks as it did applies each one to the picture beneath it, as in Photoshop, and recolours the layers it affects so they show the adjusted picture; it then can't be changed. When colours come in as swatches, each layer keeps its palette, one adjusted colour for each it had, and a Normal, Multiply or Screen layer keeps its blend mode, so an orange Multiply layer stays one orange; where a layer is soft (translucent, or under a soft mask) its pixels' transparency is adjusted instead, as if the curve were applied to the mask. When colours come in free, each affected layer is set to Normal and worked out pixel by pixel to match Photoshop, which can turn a glow or a fog into an image fill. A file saved with Maximize Compatibility carries Photoshop's own picture of itself, and with Looks as it did, a layer that isn't under a blended layer takes its colours from that picture wherever it can, so it shows exactly what Photoshop showed. Some adjustments, such as Hue/Saturation and Colour Balance, come out close to Photoshop's but not identical either way, and a file saved in another colour space than sRGB matches Photoshop only with Looks as it did.

Clipping masks come across as clipping masks. A layer mask becomes a mask beneath the layer, and the two are grouped under the layer's name. It is painted in white as a free colour, with the mask's greys as its opacity, so it stays out of the palette; a vector mask becomes a mask drawn as a shape, the same way; a turned-off mask comes in hidden. A frame animation from Photoshop's Timeline comes in as sprites: each layer or group that changes between frames becomes a sprite in its place, playing one frame for each state it takes, and those frames are built to the right of the artboard. The rest of the layers stay as they are, showing the frame that was selected when the file was saved. Untick Bring in the timeline's frames as sprites to import only the frame the file was saved on. Not supported yet: inverted vector masks, mask feathering, layer effects other than Color Overlay, colour lookup adjustments, and the Dissolve blend mode, which imports as Normal. When something is dropped, the import notes say which layers were affected.

Artboards

An artboard marks a part of the canvas to export: an icon, a sticker, a frame of an animation. Draw one with the Artboard tool A, inside another artboard too; drag an artboard by its edge or name to move it. The Artboards panel lists them, and an artboard can be turned into a frame and back.

The artwork's picture on the Artworks page shows everything in it, until you draw its first artboard, which becomes the cover. To show another part, right-click an artboard, a frame or an instance and choose Set as cover. The cover's label on the canvas and its row in the Contents or Artboards panel carry a cover mark. Choose it again to go back to the whole artwork.

Grids

The Grids panel holds the artwork's own grids, rectangular or in perspective. A grid is a guide while you work and isn't part of the picture, unless you give it strokes or fills under Ink in Properties: those draw it into the artwork, over a rectangle or the frame it's in. ⇧. shows and hides the grids. Items snap to a visible grid while its Snap is on. A rectangular grid can also be a pixel tool's, a fill's or a dither's Lattice. Drag from a ruler to pull out a single guide.

Moving around

⌘1 to ⌘4 zoom to 1×, 2×, 3× and 4×, and ⇧1 fits the selection to the window, or the whole artwork when nothing is selected. ⇧G shows the pixel grid, ⌥R the rulers and ⇧B the artboards' edges.

Viewfinders

A viewfinder is a second window onto the same artwork, with its own zoom and position. Open one with ⌘⌥V, or isolate an item in one from the Contents panel. It's a good way to watch a detail at 1× while you draw it zoomed in. In a complex artwork, isolating a large group of layers in a viewfinder lets you work on that part alone. ⌘H minimises the active viewfinder. Right-click the canvas and choose Open in Viewfinder to put the canvas itself in one, and Fullscreen in a viewfinder's right-click menu to make it the canvas. With no canvas, right-click the empty space and choose Reopen Fullscreen Canvas; closing the last viewfinder brings it back too. A floating viewfinder shows the plain picture, a working view; Visual effects in its View toggles runs the artwork's effects over it as the canvas does.

A frame or an artboard can have visual effects of its own, under Visual effects in its Properties: they run over what's inside its box, after the artwork's, on the canvas and when it's exported. Effect rows are selected with a click, ⌘-click adds or takes away one and ⇧-click a run; ⌘C, ⌘X and ⌘V, or a row's right-click menu, copy, cut and paste them, so effects move between the artwork's list and a frame's, or into another artwork. Not supported yet: a frame's own effects on the canvas in a browser without WebGPU, and a frame's own effects inside something larger being exported.