Images from Code

A picture you load in Python can be changed in code: cut out its subject, resize it, crop, rotate, trace it into vector shapes, read what is in it. Each change gives you a new picture in memory, ready to draw, to show in a Pymations scene, or to save beside your .py file.

img = load_image("shoe.jpg")               # a picture beside this .py
cut = await img.remove_background()        # the shoe, background transparent (Apple devices only)
small = await cut.resize(width=800)        # one step after another
await small.save("shoe cutout.png")        # optional: write it beside the .py

Where each method runs

The work is done by the Circuitry app, so these methods run in scenes inside Circuitry. They are not part of a scene exported as a web page, or of the open-source Pyctures library run on its own. A JavaScript (pictures.js) scene has the same methods, in JavaScript's spelling: Images from Code for pictures.js.

Inside Circuitry, what a method needs depends on the method:

• Any device Web, Mac, Windows, Linux, iPhone, iPad and Android: resize, crop, rotate, flip, convert, trace, threshold, edge_detect, canny_edges, find_contours, detect_shapes, watermark, strip_metadata, favicon_set, app_icon_set, save.
• Apple devices The Circuitry app on a Mac, iPhone or iPad, or a browser connected to Circuit running on a Mac: remove_background, enhance, sepia, mono, noir, vintage, blur, sharpen, vibrance, and the photo tools classify, find_faces, read_codes, photo_details, hide_faces, scan_document, smart_crop, straighten.

The photo tools on a Mac need the current version. classify, find_faces, read_codes, photo_details, hide_faces, scan_document, smart_crop and straighten first ran only in the iPhone and iPad app. On a Mac they need the updated Circuitry desktop app, or the updated Circuit when a browser, phone or tablet is connected to one. With an older app or Circuit they are not offered: available() leaves them out, and calling one stops with a message that says what it needs.

The Apple-only ones use the picture tools built into Apple's systems (Vision and Core Image), which work on the device itself. They are not Apple Intelligence: no Apple Intelligence model or setting is involved, and nothing is sent to a server.

System versions. iOS 17 / macOS 14 or later remove_background needs iOS 17, iPadOS 17 or macOS 14 or later, the first versions with Apple's subject lifting. Every other method here runs on any system version the Circuitry app itself runs on. None of them needs iOS, iPadOS or macOS 27.

A method called where it cannot run stops with a message that says where it does. Every method lists each one with where it runs, and await img.available() gives the names this device can run.

How it works

• load_image("name.png") loads a picture from the folder your .py is saved in (or a web address). You can draw it straight away, as before: ctx.drawImage(img, 0, 0), or Sprite(img).
• Every method is awaited: await img.resize(width=800). Put the code at the top level of the file, or inside an async def (in Pymations, async def construct(self)).
• A method never changes the picture you called it on. It returns a new one, so you can keep both, or chain: await (await img.remove_background()).resize(width=800).
• The work happens in the app, not in Python, so even big photos stay quick and nothing is copied into your program.
• Results are remembered. Running the file again, or recording a video of it, reuses the results instead of redoing the work, as long as the picture file and the settings are the same.
• Nothing is written to disk unless you call save().

Remove a background

product = load_image("bottle.jpg")
cutout = await product.remove_background()
ctx.drawImage(cutout, 100, 80)

remove_background() finds the main subject (a product, a person, a pet) and makes everything else transparent. It uses Apple's own on-device subject lifting, so it needs the Circuitry app on a Mac (macOS 14 or later), iPhone or iPad (iOS / iPadOS 17 or later), or a browser connected to Circuit running on a Mac. Anywhere else the line stops with: remove_background() needs an Apple device. On iPhone and iPad it needs a real device; it does not run in the iOS Simulator.

Resize a picture

hero = await img.resize(width=1280)             # height follows the shape
thumb = await img.resize(percent=25)
square = await img.resize(width=1080, height=1080)               # whole picture, centred
cover = await img.resize(width=1080, height=1080, fit="cover")   # fill the square, trim the edges

Give width, height or percent. With both width and height, fit says how the picture fills the box: "contain" (the default: the whole picture, with clear margins), "cover" (fills the box and trims the edges) or "stretch". Big reductions are made in halves before the final size, so detail and text stay sharp. Transparency is kept.

Trace a picture into shapes

logo = load_image("logo.png")
vec = await logo.trace(colors=6, detail="medium")
await vec.save("logo.svg")

trace() turns a picture into flat-colour vector shapes, the same tracing 2Vec uses. colors is how many colours to keep; detail is "low" (smoother, fewer points), "medium" or "high". A logo or an illustration with clear areas of colour traces best; a photo becomes a poster-like picture. The result is a Vector: vec.svg is its SVG text, vec.shapes how many shapes it has.

In Pymations

from pymations import *

class Product(Scene):
    async def construct(self):
        shoe = await load_image("shoe.jpg").remove_background()
        self.play(FadeIn(ImageMobject(shoe).scale(0.8)))

        vec = await load_image("logo.png").trace(colors=5)
        logo = SVGMobject(vec)            # or vec.to_mobject()
        self.play(DrawBorderThenFill(logo))

• ImageMobject(picture) shows any picture, loaded or changed.
• SVGMobject(vec) (or vec.to_mobject()) turns a traced picture into one shape per traced region, each with its own colour, so animations that draw outlines and fill shapes work on it.
• In an ordinary def construct(self) (no await), give the changes to the object itself and the scene waits for them: ImageMobject("shoe.jpg", remove_background=True, resize=800), ImageMobject("photo.jpg", ops=[("crop", {"x": 0, "y": 0, "width": 600, "height": 400}), ("sepia",)]), or SVGMobject("logo.png", trace={"colors": 5, "detail": "medium"}) for traced shapes. remove_background runs first, then ops, then resize (a number is a width).

Data from a picture

Some methods read a picture instead of changing it, and return Python data. classify, find_faces, read_codes and photo_details need an Apple device (the Circuitry app on a Mac, iPhone or iPad, or Circuit running on a Mac); find_contours and detect_shapes run everywhere.

info = await img.classify()
for item in info.labels:             # e.g. {"label": "shoe", "confidence": 0.93}
    print(item["label"], item["confidence"])

codes = await img.read_codes(overlay=False)
for code in codes.codes:             # each has "symbology" and "payload"
    print(code["payload"])

Methods that can draw what they found (find_faces, read_codes, find_contours, detect_shapes) return {"found": ..., "overlay": picture} when overlay=True (their default), so you can show the finds; pass overlay=False for the data alone.

Saving

await pic.save("name.png") writes beside your .py (.png, .jpg or .webp; the format follows the name) and returns the path. It replaces a file of that name. A traced Vector saves as .svg. favicon_set() and app_icon_set() make a set of files: await icons.save("icons") writes them into a folder. Save the .py first: saving uses the folder it is in.

What this device can run

print(await img.available())    # the method names this device can run

Most methods run everywhere. Apple's effects and the photo tools (classify, find_faces, read_codes, photo_details, hide_faces, scan_document, smart_crop, straighten) need an Apple device: the Mac app, iPhone or iPad, or Circuit on a Mac. On a Mac the photo tools need the updated desktop app or Circuit, so the list is the way to know what this one has. Calling a method where it cannot run stops with a message that says where it does.

Every method

Every picture has these methods. Each is awaited (await img.resize(width=800)); keywords you leave out take the default shown. await img.run("name", **keywords) runs any of them by name.

Related

• Images from Code for pictures.js: the same methods in a JavaScript scene.
• Plain Python Files: read and write other files beside your script.
• Maths Animations (Pymations): explainer videos in Python.
• Drawing in 2D: drawing pictures with ctx.