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
small = await cut.resize(width=800)        # one step after another
await small.save("shoe cutout.png")        # optional: write it beside the .py

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, iPhone or iPad, 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 run in the iPhone and iPad app; 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 need an Apple device (the Mac app, iPhone or iPad, or Circuit on a Mac), and a few photo tools run only in the iPhone and iPad app. Calling one 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

• Using Your Files: read and write other files beside your script.
• Maths Animations (Pymations): explainer videos in Python.
• Drawing in 2D: drawing pictures with ctx.