`image(...)` — pictures

image() puts a picture on the stage: one file, a folder of plates dealt out in a different order each time, a slideshow, a picture chosen by the same kind of pattern that chooses a sound.

image(src:cloud.png)                       one file, shown when triggered
image(path:plates, mode:shuffle)           a folder, a different one each pass
image(src:Pseq(a.png, b.png, inf))         an explicit order
image(path:plates, mode:seq, dur:2)        a slideshow, two beats a frame

Where the pictures live

In the images/ folder of Live's own media folder (_live, on Oscilla's server), beside audio/ and video/, with folders of pictures inside it (images/plates/).

path:plates takes everything in that subfolder. PNG, JPEG, GIF, WebP, AVIF, SVG and BMP are recognised.

On the stage

A line has no element, so it makes a frame of its own on the stage, placed as a shape is: at: the middle (0..1 of the view), size: a share of the view across and down -- 1, the default, all of it; [w, h] apart. One frame for each uid: the line run again shows in it, or moves it. sh1 > image(...) puts the picture in that shape's box instead.

image(uid:sky, src:"https://…/sky.jpg")                       the whole view
image(uid:p, src:"https://…/plate.png", at:[0.75, 0.3], size:0.3)
sh1 > image(src:"https://…/plate.png")                        in shape sh1
image(uid:p, remove:1)                                         taken away (remove:all: every one)

Oscilla Live on Oscilla's server has a folder of its own (its landing says where), so path:plates deals out images/plates/ there as in a project, slideshows, patterns and all:

image(uid:pl, path:plates, mode:seq, dur:0.5, size:0.5)       a slideshow, half a beat a frame
image(uid:fs, path:plates, mode:shuffle, dur:1, size:fullscreen)

On a plain static host there is no folder to list: give URLs (src:Pseq(…) of them steps through them).

Effects

A picture takes the effects a sound's box does, from gui() by its uid -- blur, the ripple of warp: (grain: its size), hue:, invert:, contrast:, saturate:, bright:, pixel:, split: -- each a number or a follow(). They stay on as a slideshow changes the picture.

gui(pl, blur:2, warp:20, hue:120)
gui(pl, warp:follow(bass.level, 0, 40))
gui(pl, fx:off)

Parameters

Key	Default	Description
`src`	—	One file, or a pattern of files: `Pseq`, `Prand`, `Pxrand`, `Pshuf`, `Pchoose`
`path`	—	A folder inside `images/`. Every picture in it becomes the pool
`glob`	—	Filter the folder, `` and `?` wildcards: `glob:plate-.png`
`mode`	`shuffle`	Which one next, see below
`fit`	`contain`	`contain` shows the whole picture letterboxed, `cover` fills the box and crops, `fill` stretches
`dur`	—	Beats per picture. Without it, one picture per trigger; with it, a slideshow
`fade`	`0`	Fade in and out, in beats. `fadein` / `fadeout` set them separately
`opacity`	`1`	0 to 1
`uid`	element id	Cues sharing a uid share a position in the folder, so two frames can deal from one pack

Fullscreen

size:fullscreen puts the picture over the whole window.

image(src:plate.jpg, size:fullscreen, close:1, fade:0.4)
image(path:plates, size:fullscreen, dur:3, hold:30, backdrop:1)
image(src:ground.jpg, size:fullscreen, layer:under, opacity:0.4)

Key	Default	Description
`size`	—	`fullscreen` (or `fs`) for the whole window
`layer`	`over`	`over` the score, or `under` it — a ground the notation is read against
`backdrop`	`1`	Dim the score behind the picture. `backdrop:0` leaves it visible
`close`	`0`	A close button in the corner
`clickclose`	`0`	Click the picture itself to dismiss it
`hold`	—	Beats up, then it goes by itself

Getting out again, in order of how deliberate they are: hold: takes it away on a timer, close:1 gives a button, clickclose:1 lets a press anywhere on the picture dismiss it, and Escape always works — a fullscreen picture is the first thing Escape backs out of, one press per picture, the same as a fullscreen video.

dur: and hold: do different jobs and combine: dur: is the step of a slideshow, hold: is how long the whole thing stays. image(path:plates, size:fullscreen, dur:2, hold:20) deals a new plate every two beats and gives up after twenty.

Layering follows the video cue: backdrop, picture, close button in that order, above the score. layer:under drops the picture beneath the notation instead.

Modes

shuffle — a fresh random order each time through the folder, so nothing repeats until everything has been seen. The usual choice.
seq — in order, wrapping round at the end.
random — chosen independently every time, so repeats happen.
once — through the folder once, then nothing further.

Two cues with the same uid draw from one pool and one cursor, so three frames on a page can show three different pictures from the same folder rather than three copies of the same one:

image(path:plates, uid:pack, mode:shuffle)
image(path:plates, uid:pack, mode:shuffle)
image(path:plates, uid:pack, mode:shuffle)

Examples

// a cover that appears once and stays
image(src:cover.png, fit:cover, fade:1)

// performer-triggered
image(path:plates, mode:random, trig:click)

Opacity from another object

opacity takes a follow(), so anything publishing a 0-1 signal can dim the picture live:

image(uid:plate, src:horse.jpg, opacity: follow(fader.t))

The two cues know nothing about each other — the fader publishes fader.t, the image follows it. Any 0-1 source works: an o2p() dot's travel along its path (follow(dot.t)), a controlXY handle (follow(pad.y)), mic amplitude (follow(adc.amp)), or an incoming OSC address (follow(/pedal/1)).

In a sequence the binding follows the pictures: each new frame is placed at the current value rather than at the one written in the score.

Picking the plate with a signal

A folder is normally dealt out — mode:seq steps through it, mode:shuffle reorders it. index: turns it into a lookup table instead: something else chooses which plate is showing.

image(uid:plate, path:horse, index: follow(dial.t))

With no range, follow() spans the whole folder: 0 is the first file, 1 the last. Give numbers to use part of it — follow(dial.t, 3, 8) scrubs the middle six plates only. Values are rounded to the nearest file and clamped, so a source that overshoots holds at an end rather than going blank.

While index: is bound, dur: is ignored — something else is doing the advancing. Reloading the same plate is skipped, so a slow-moving source does not thrash the image element.

This is how you scrub a frame sequence by hand, or drive it from anything that moves: a rotate()'s angle, a trans() bar's progress, a controlXY handle, an incoming OSC pedal.

What an image publishes

An image() reports which plate it is on, so the pictures can drive something else in turn:

Channel	Meaning
`index`	which file, 0-based within the folder
`t`	the same position as 0–1

image(uid:plate, path:horse, mode:seq, dur:0.12)
synth(uid:s1, wave:sine, freq: follow(plate.t, 200, 900), amp:0.1)

A src: pattern of explicit filenames has no folder to be a position in, so it publishes nothing — only a path: folder (or a file list) has an index.

Tip: use ← → or ↑ ↓ to navigate the docs

image(...) — pictures