Skip to main content

•image — Images

•image Y returns a picture: an array of numbers from 0 to 1, with axes for rows, columns and up to four channels, that notebooks display as an image. One channel is grey, two are grey and alpha, three are red, green and blue, and four are red, green, blue and alpha. Y is the path of a PNG or JPEG file, the bytes of one, or the numbers themselves. On a Mac, •image also reads the other formats that macOS’s ImageIO reads, such as GIF, TIFF, WebP and BMP, with an animation’s frames along a first axis. On other platforms, •image reads PNG and JPEG only. Values outside 0 to 1 are clipped when the picture is displayed or encoded.

•image⁻ Y encodes the picture Y as PNG bytes. Its left argument is an options record with the keys format ("png" or "jpeg"), fps and delay. A text left argument gives the format, as in "jpeg" •image⁻ Y. Encoding as JPEG drops the alpha channel. •nput writes the bytes to a file, as in "out.png" •nput •image⁻ Y.

An animation has frames along its first axis. A rank-4 array, frames by rows by columns by channels, is an animation. ["fps":12] •image Y or ["delay":0.1] •image Y treats the first axis of Y as frames, whatever its rank. A grey animation then needs no channel axis. fps sets the frame rate, 24 frames a second by default. delay sets the seconds each frame stays on screen: one number for every frame, or one per frame. delay takes precedence over fps. ["delay":(9ρ0.1),2] •image Y holds the last of 10 frames for 2 seconds. Notebooks and the playground play an animation as an animated PNG. •image⁻ encodes an animation as an animated PNG, and takes the same options. •image reads an animated PNG back as a rank-4 array, with a channel axis even for grey frames.

Errors: DOMAIN for an unknown format, invalid image bytes, values that aren’t real numbers, an fps or delay that isn’t positive, or an animation encoded as JPEG; LENGTH for a delay whose length is neither 1 nor the number of frames; RANK for a shape that isn’t a picture or an animation; IO for file errors.