Reference · Media

image.info

image.info(str) -> map | error(str)

What it does

The size and kind of an image file, from its header alone: { width, height, format, alpha }, with format one of jpeg, png, webp and gif. The pixels are not decoded, so it is a cheap check that an upload is an image at all. width and height are the image as it is shown: a photo's EXIF orientation is applied, so a portrait taken on a phone and stored sideways reports its upright size, as image.convert turns it. The path is inside the program's folder. A file that is missing or not an image is an error value. It needs the fs effect.

Examples

let info = image.info("photos/a.jpg")           // { width: 4032, height: 3024, format: "jpeg", alpha: false }if info.width > 800 { image.convert("photos/a.jpg", "cache/a-800.jpg", { width: 800 }) }

A one-pixel GIF, written as text since every byte of it is below 128:

write_file("tiny.gif", "GIF89a\u0001\u0000\u0001\u0000\u0000\u0000\u0000,\u0000\u0000\u0000\u0000\u0001\u0000\u0001\u0000\u0000\u0002\u0002D\u0001\u0000;")print(image.info("tiny.gif"))print(image.info("tiny.gif").width)delete_file("tiny.gif")

{ width: 1, height: 1, format: "gif", alpha: true }1

Edge cases

• A file that is not there is an error value, as is one that is not a JPEG, PNG, WebP or GIF: a .png that holds text, for instance.
• An image claiming more than 12,000 pixels a side is an error value, before anything is allocated.
• The format comes from the bytes, not the file's name.
• A GIF is reported with alpha true.

print(image.info("nothing.png"))print(image.info("main.qwe"))write_file("photo.png", "GIF89a\u0001\u0000\u0001\u0000\u0000\u0000\u0000,\u0000\u0000\u0000\u0000\u0001\u0000\u0001\u0000\u0000\u0002\u0002D\u0001\u0000;")print(image.info("photo.png").format)delete_file("photo.png")

err("image: No such file or directory (os error 2)")err("image: not a JPEG, PNG, WebP or GIF image")gif

Errors

A missing or unreadable image is an error value: check with is_err, give a default with ??, or pass it on with ?. A path outside the program's folder, or one that is not a string, is a runtime error.

let r = image.info("nothing.png")print(is_err(r), r.error)print(image.info("nothing.png") ?? { width: 0, height: 0 })

true image: No such file or directory (os error 2){ width: 0, height: 0 }

print(image.info("../secret.png"))

line 1: `image.info`: "../secret.png" is not a path inside the program's folder

Chaining

The path is its only argument, so it pipes in; ? in a route turns a bad upload into the request's answer.

route POST /avatar { files: { photo } } {    let path = save_upload(photo, "uploads")    let info = image.info(path) ?? reply 400 "not an image"    image.convert(path, `avatars/${session().user}.jpg`, { width: 256 })?    redirect("/me")}

print(["a.png", "b.png"] | map(image.info) | map(is_err))

[true, true]

See also

image.convert, save_upload, write_file, is_err

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo