Function index
Every name a pictures.js scene can use, by area, one line each. The link on each row goes to the page that explains it, with examples.
| Area | pictures.js | Pyctures |
|---|---|---|
| 2D drawing: the plain functions | Yes | Yes |
2D drawing: the canvas, ctx | Yes | Yes |
| 3D: three.js | Yes | Yes |
| Sprites and hit-testing | Yes | Yes |
| Keyboard, mouse and touch | Yes | Yes |
| Frames and timing | Yes | Yes |
| Saved values | Yes | Yes |
| Files | Yes | Yes |
| Databases (SQLite) | Yes | Yes |
| Image processing | Yes In Circuitry only | Yes In Circuitry only |
This page is pictures.js's own index, in its own spellings. Pyctures has the same areas in Python: the Pyctures function index.
Everything here works everywhere Circuitry runs (iPhone, iPad, Android, the desktop app and a web browser) and in a page made with File, Export as Web Page, unless its row has a badge that says otherwise. In Circuitry only means inside Circuitry, and not in the pictures.js library used on its own or in an exported page.
The shape of a scene
Functions you write. They are called if the scene defines them.
Explained in How a program is shaped.
| Name | What it does |
|---|---|
setup() | Called once, before the first frame. It can be an async function |
update(dt) | Called every frame, with the seconds since the last one: move things here |
draw() | Called every frame, after update: draw the picture here |
onStop() | Called when the scene stops or is run again: let go of what it made outside the canvas |
2D drawing: the plain functions
One call each, with no ctx. in front.
Explained in 2D functions.
| Name | What it does |
|---|---|
background(colour) | Paints the whole canvas |
circle(x, y, radius, colour) | A filled circle centred on x, y |
ellipse(x, y, width, height, colour) | An oval centred on x, y |
rect(x, y, width, height, colour) | A filled rectangle, top-left corner at x, y |
triangle(x1, y1, x2, y2, x3, y3, colour) | A triangle, by its three corners |
polygon(x, y, radius, sides, colour) | A shape with that many equal sides, centred on x, y, one corner straight up |
star(x, y, radius, points, colour) | A star with that many points, one straight up |
line(x1, y1, x2, y2, colour, thickness) | A straight line |
text(words, x, y, colour, size, align) | Words, size points high |
picture(what, x, y, size) | An emoji or a word, an image file beside the program, or a loaded image, centred on x, y and … |
Chance and angles
Explained in 2D functions.
| Name | What it does |
|---|---|
random(min, max) | A whole number from min to max, either end included |
random(max), random() | From 0 to max; with nothing, a fraction from 0 up to 1 |
pick(list) | One thing from a list, by chance |
degrees(n) | An angle said in degrees, wherever an angle is wanted: ctx.rotate(degrees(45)), ship.angle = … |
2D drawing: the canvas, ctx
The web's own 2D drawing surface: everything the plain functions do, and much more.
Size and pictures
Explained in 2D functions.
| Name | What it does |
|---|---|
width, height | The size of the canvas, in points |
pixelRatio | Real pixels per point (2 or 3 on most phones) |
canvas | The canvas, for canvas.addEventListener(...) |
loadImage(address) | Loads a picture to draw |
Rectangles
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.fillRect(x, y, w, h) | A filled rectangle, top-left corner at x, y |
ctx.strokeRect(x, y, w, h) | The outline of a rectangle |
ctx.clearRect(x, y, w, h) | Rubs that area out, back to see-through |
Paths
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.beginPath() | Starts a new, empty path |
ctx.moveTo(x, y) | Lifts the pen and puts it down at x, y |
ctx.lineTo(x, y) | A straight line to x, y |
ctx.closePath() | A straight line back to where this piece started |
ctx.rect(x, y, w, h) | A rectangle, as part of the path |
ctx.roundRect(x, y, w, h, r) | A rounded rectangle |
ctx.arc(x, y, r, start, end) | Part of a circle round x, y, from angle start to end in radians (0 to Math.PI * 2 is … |
ctx.arcTo(x1, y1, x2, y2, r) | A rounded corner of radius r, turning at x1, y1 towards x2, y2 |
ctx.ellipse(x, y, rx, ry, turn, start, end) | Part of an oval, rx wide and ry tall, turned by turn radians |
ctx.quadraticCurveTo(cx, cy, x, y) | A curve to x, y, pulled towards one control point |
ctx.bezierCurveTo(c1x, c1y, c2x, c2y, x, y) | A curve to x, y with two control points |
ctx.fill() | Fills the path |
ctx.stroke() | Draws the path's outline |
Colours and styles
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.fillStyle = … | The colour, gradient or pattern for fills and filled text |
ctx.strokeStyle = … | The same, for outlines |
ctx.globalAlpha = 0.5 | How solid everything drawn next is, from 0 (invisible) to 1 |
ctx.createLinearGradient(x0, y0, x1, y1) | A gradient along a line |
ctx.createRadialGradient(x0, y0, r0, x1, y1, r1) | A gradient between two circles |
ctx.createConicGradient(angle, x, y) | A gradient round a point, like a colour wheel |
gradient.addColorStop(position, colour) | A colour at a point (0 to 1) along a gradient |
ctx.createPattern(picture, "repeat") | A repeating fill from a picture or another canvas |
Lines
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.lineWidth = 4 | How thick outlines are, in points |
ctx.lineCap = "round" | How line ends look: "butt" (flat, stops at the end), "round", "square" (flat, sticks out … |
ctx.lineJoin = "round" | How corners look: "miter" (sharp), "round", "bevel" (cut off) |
ctx.miterLimit = 10 | How far a sharp corner may stick out before it is cut off like a bevel |
ctx.setLineDash([10, 5]) | Dashes: 10 drawn, 5 gap |
ctx.getLineDash() | The current dash list |
ctx.lineDashOffset = 4 | Slides the dashes along |
Text
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.fillText(text, x, y) | Draws text |
ctx.strokeText(text, x, y) | Draws the outline of the text |
ctx.measureText(text).width | How wide the text will be, in points, in the font set now |
ctx.font = "bold 24px serif" | Style, size and family |
ctx.textAlign = "center" | Where x is: "left", "center", "right", or "start"/"end" (which follow the writing … |
ctx.textBaseline = "middle" | Where y is: "alphabetic" (the line letters sit on, the default), "top", "hanging" … |
ctx.direction = "rtl" | Writing direction: "ltr", "rtl" or "inherit" |
ctx.letterSpacing = "4px" | Extra space between letters (older devices ignore it) |
ctx.wordSpacing = "10px" | Extra space between words (older devices ignore it) |
ctx.fontKerning = "none" | Whether letter pairs are fitted closer: "auto", "normal", "none" |
Images
Explained in 2D functions.
| Name | What it does |
|---|---|
const img = loadImage(address) | Starts loading a picture from a path beside the scene ("cat.png"), a web address (asked about … |
ctx.drawImage(img, x, y) | Draws it at its own size, top-left at x, y |
ctx.drawImage(img, x, y, w, h) | Draws it stretched to w by h |
ctx.drawImage(img, sx, sy, sw, sh, x, y, w, h) | Cuts the part sx, sy, sw, sh out of the picture and draws it at x, y, w, h |
ctx.imageSmoothingEnabled = false | Keeps pixel art crisp and blocky when scaled up |
ctx.imageSmoothingQuality = "high" | How carefully pictures are smoothed: "low", "medium", "high" |
Transforms
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.translate(x, y) | Moves the grid's corner (0, 0) to x, y |
ctx.rotate(angle) | Turns the grid round (0, 0) by angle radians, clockwise |
ctx.scale(sx, sy) | Stretches the grid |
ctx.transform(a, b, c, d, e, f) | Applies any stretch, slant and move at once |
ctx.save() | Remembers the transform and every setting on this page |
ctx.restore() | Goes back to what the last save() remembered |
ctx.setTransform(a, b, c, d, e, f) | Replaces the transform completely |
ctx.resetTransform() | Clears the transform |
ctx.getTransform() | The current transform, with its numbers as a to f |
Shadows
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.shadowColor = "rgba(0, 0, 0, 0.5)" | The shadow's colour |
ctx.shadowBlur = 10 | How soft the shadow is |
ctx.shadowOffsetX = 5 | How far right the shadow falls |
ctx.shadowOffsetY = 5 | How far down the shadow falls |
Blending and filters
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.globalCompositeOperation = "multiply" | How new drawing mixes with what is already there |
ctx.filter = "blur(4px)" | An effect on everything drawn next |
Clipping and hit testing
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.clip() | Makes the current path a window: everything drawn next shows only inside it |
ctx.isPointInPath(x, y) | Whether a point is inside the current path: true or false |
ctx.isPointInStroke(x, y) | Whether a point is on the path's outline |
Paths you can keep: Path2D
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.fill(path) | Fills that path |
ctx.stroke(path) | Outlines it |
ctx.clip(path) | Clips to it |
ctx.isPointInPath(path, x, y) | Whether a point is inside it |
path.addPath(other) | Adds another path's pieces to this one |
Pixels
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.getImageData(x, y, w, h).data | The colours of every pixel in that area, as one long list: red, green, blue, alpha (0 to 255) … |
ctx.createImageData(w, h) | A blank block of pixels |
ctx.putImageData(pixels, x, y) | Puts a block of pixels straight onto the canvas, ignoring transforms, alpha and blend modes |
new ImageData(new Uint8ClampedArray(numbers), w, h) | Makes a block of pixels from a list of numbers |
Saving and resetting
Explained in 2D functions.
| Name | What it does |
|---|---|
ctx.save() | Remembers every setting on this page, the transform and the clip |
ctx.restore() | Goes back to the last save() |
ctx.reset() | Clears the canvas and puts every setting back to the start, including the canvas's sharp-screen … |
3D: three.js
three.js is there as THREE, and its orbit controls as addons.OrbitControls.
Renderer
Explained in 3D functions.
| Name | What it does |
|---|---|
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true }) | Makes a renderer that draws on the canvas, with smooth edges |
renderer.setPixelRatio(pixelRatio) | Sharp on high-resolution screens |
renderer.setSize(width, height, false) | Fits the canvas |
renderer.render(scene, camera) | Draws one picture; call it in draw() |
renderer.setClearColor("navy", 1) | The colour behind the scene when it has no background; the second number is how solid |
renderer.shadowMap.enabled = true | Turns shadows on |
renderer.shadowMap.type = THREE.PCFSoftShadowMap | Soft-edged shadows |
renderer.toneMapping = THREE.ACESFilmicToneMapping | Softens very bright light the way a film camera does |
renderer.toneMappingExposure = 1.2 | Overall brightness when tone mapping is on |
renderer.outputColorSpace = THREE.SRGBColorSpace | How colours are sent to the screen |
Scene and fog
Explained in 3D functions.
| Name | What it does |
|---|---|
const scene = new THREE.Scene() | The world everything goes in |
scene.add(thing), scene.remove(thing) | Puts something in the world, or takes it out |
scene.background = new THREE.Color("skyblue") | The colour behind everything |
scene.fog = new THREE.Fog("white", near, far) | Fog that starts at distance near and hides everything by far |
scene.fog = new THREE.FogExp2("white", 0.05) | Fog that thickens steadily with distance; the number is how thick |
Cameras
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.PerspectiveCamera(fov, width / height, near, far) | A camera that sees the way eyes do: far things look smaller |
new THREE.OrthographicCamera(left, right, top, bottom, near, far) | A camera with no perspective: far things look the same size |
camera.position.set(x, y, z) | Where the camera is |
camera.lookAt(x, y, z) | Points it at a spot |
camera.aspect = width / height | The shape of a perspective camera's picture; follow with camera.updateProjectionMatrix() |
camera.fov = 30, camera.near, camera.far, camera.zoom = 2 | Change its settings; follow with camera.updateProjectionMatrix() |
camera.updateProjectionMatrix() | Applies changed camera settings |
Geometries: shapes
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.BoxGeometry(w, h, d) | A box |
new THREE.SphereGeometry(radius, 32, 16) | A ball |
new THREE.PlaneGeometry(w, h) | A flat rectangle, facing you |
new THREE.CircleGeometry(radius, 32) | A flat disc |
new THREE.RingGeometry(inner, outer, 32) | A flat ring, like a washer |
new THREE.CylinderGeometry(topRadius, bottomRadius, height, 32) | A cylinder; different radii make a tapered tube |
new THREE.ConeGeometry(radius, height, 32) | A cone |
new THREE.CapsuleGeometry(radius, length, 8, 16) | A pill |
new THREE.TorusGeometry(radius, tube, 16, 64) | A ring doughnut |
new THREE.TorusKnotGeometry(radius, tube, 128, 16) | A knotted tube |
new THREE.TetrahedronGeometry(radius) | 4 faces |
new THREE.OctahedronGeometry(radius) | 8 faces |
new THREE.DodecahedronGeometry(radius) | 12 faces |
new THREE.IcosahedronGeometry(radius, detail) | 20 faces; raise detail to make it rounder |
new THREE.LatheGeometry(points, 32) | Spins a side outline (a list of THREE.Vector2) round the up axis, like a vase on a potter's … |
new THREE.ExtrudeGeometry(shape, { depth: 0.5, bevelEnabled: false }) | Pushes a flat THREE.Shape out into a solid, like a cookie cutter |
new THREE.TubeGeometry(curve, 64, radius, 8, false) | A tube along a curve, such as new THREE.CatmullRomCurve3([...points]) |
new THREE.EdgesGeometry(geometry) | Just the edges of another shape, for LineSegments |
new THREE.WireframeGeometry(geometry) | Every triangle's edges, for LineSegments |
new THREE.BufferGeometry() | Your own shape from numbers: geometry.setAttribute("position", new … |
Materials: how surfaces look
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.MeshBasicMaterial({ color: … }) | Flat colour, ignores light, always visible |
new THREE.MeshLambertMaterial({ color: … }) | Matte, like chalk or paper |
new THREE.MeshPhongMaterial({ color: …, shininess: 80, specular: "white" }) | Shiny highlights, like plastic |
new THREE.MeshStandardMaterial({ color: …, roughness: 0.5, metalness: 0 }) | Realistic |
new THREE.MeshPhysicalMaterial({ color: …, clearcoat: 1, transmission: 0.9, thickness: 0.5 }) | Standard, plus extras: clearcoat (a varnish layer), transmission (glass that lets light … |
new THREE.MeshToonMaterial({ color: … }) | Cartoon shading in a few flat bands |
new THREE.MeshNormalMaterial() | Rainbow colours by which way each face points; needs no light |
new THREE.MeshDepthMaterial() | White near the camera, fading to black far away |
new THREE.LineBasicMaterial({ color: … }) | For lines (Line, LineSegments, LineLoop) |
new THREE.LineDashedMaterial({ color: …, dashSize: 0.2, gapSize: 0.1 }) | Dashed lines; call line.computeLineDistances() once |
new THREE.PointsMaterial({ color: …, size: 0.05 }) | For Points |
new THREE.SpriteMaterial({ map: texture }) | For THREE.Sprite, a picture that always faces the camera |
color: "tomato" | The surface colour |
emissive: "orange", emissiveIntensity: 1 | A glow the surface gives off by itself |
map: texture | A picture wrapped round the surface |
roughness, metalness | Standard and Physical only: rough or polished, metal or not |
wireframe: true | Draws the edges of every triangle only |
flatShading: true | Shows the flat faces rather than smoothing over them |
side: THREE.DoubleSide | Shows both sides of flat shapes (FrontSide is the default, BackSide the inside) |
transparent: true, opacity: 0.5 | See-through; opacity does nothing without transparent |
Lights
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.AmbientLight(colour, intensity) | A little light everywhere, from no direction |
new THREE.HemisphereLight(sky, ground, intensity) | Sky colour from above, ground colour from below |
new THREE.DirectionalLight(colour, intensity) | The sun: parallel light from position towards target (the middle unless you move it) |
new THREE.PointLight(colour, intensity, distance, decay) | A bulb: light in every direction from one spot |
new THREE.SpotLight(colour, intensity, distance, angle, penumbra, decay) | A torch: a cone of light from position towards target |
new THREE.RectAreaLight(colour, intensity, w, h) | A glowing panel, like a window or a softbox |
light.intensity = 2 | Brightness |
light.color.set("orange") | Colour |
light.position.set(x, y, z) | Where it is |
light.target.position.set(x, y, z) | Where directional and spot lights point; also scene.add(light.target) |
light.visible = false | Switches it off |
light.castShadow = true | Directional, point and spot lights can cast shadows (turn on renderer.shadowMap.enabled and … |
light.shadow.mapSize.width = 2048 (and .height) | Sharper shadows, at a cost in speed |
light.shadow.bias = -0.0005 | Removes stripy marks on surfaces that shadow themselves |
light.shadow.radius = 4 | Blurs shadow edges (with PCFSoftShadowMap off, PCFShadowMap on) |
light.shadow.camera.left / right / top / bottom | How big an area a directional light's shadows cover |
Objects
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.Mesh(geometry, material) | A solid object |
new THREE.Group() | An empty holder: things added to it move, turn and scale with it |
new THREE.Points(geometry, new THREE.PointsMaterial({ size: 0.05 })) | A dot at every position in the geometry |
new THREE.Line(geometry, material) | A line through the positions, in order |
new THREE.LineLoop(geometry, material) | The same, joined back to the start |
new THREE.LineSegments(geometry, material) | Separate lines, one for each pair of positions |
new THREE.Sprite(new THREE.SpriteMaterial({ map: texture })) | A flat picture that always faces the camera, for labels and particles |
new THREE.InstancedMesh(geometry, material, count) | Many copies of one mesh drawn at once, much faster than many meshes |
Moving and arranging
Explained in 3D functions.
| Name | What it does |
|---|---|
thing.position.set(x, y, z), thing.position.x = 2 | Where it is |
thing.rotation.set(x, y, z), thing.rotation.y += 0.01 | How it is turned round each axis, in radians |
thing.scale.set(2, 1, 1), thing.scale.setScalar(2) | How big it is along each axis |
thing.lookAt(x, y, z) | Turns it to face a spot |
thing.add(other), thing.remove(other) | Puts other inside thing, so it moves with it |
thing.visible = false | Hides it |
thing.name = "door" | A name, handy when picking |
thing.castShadow, thing.receiveShadow | Whether it makes shadows and shows them |
thing.traverse((child) => { … }) | Calls your function for thing and for everything inside it |
Textures
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.TextureLoader().load(address) | Loads a picture from a path ("textures/brick.png") or a web address, whose site must allow … |
new THREE.CanvasTexture(aCanvas) | Uses a 2D canvas you drew on as the picture: text, patterns, anything from 2D functions |
texture.needsUpdate = true | After you draw on that canvas again, shows the change |
texture.wrapS = texture.wrapT = THREE.RepeatWrapping | Lets the picture repeat across and down |
texture.repeat.set(4, 4) | How many times it repeats |
texture.colorSpace = THREE.SRGBColorSpace | Shows a photo's colours correctly |
texture.magFilter = THREE.NearestFilter | Keeps pixel-art textures blocky |
Helpers
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.GridHelper(size, divisions) | A grid on the floor |
new THREE.AxesHelper(length) | The three axes: x red, y green, z blue |
new THREE.DirectionalLightHelper(light, size) | Where a directional light is and which way it points |
new THREE.PointLightHelper(light, size) | Where a point light is |
new THREE.SpotLightHelper(light) | A spot light's cone |
new THREE.HemisphereLightHelper(light, size) | A hemisphere light |
new THREE.CameraHelper(light.shadow.camera) | The box a light's shadows cover |
new THREE.BoxHelper(thing, "yellow") | A box round an object |
Maths
Explained in 3D functions.
| Name | What it does |
|---|---|
new THREE.Vector3(x, y, z) | A position or direction in 3D |
new THREE.Vector2(x, y) | The same in 2D |
new THREE.Color(…) | A colour |
new THREE.Euler(x, y, z) | A turn round each axis, in radians: what rotation is |
new THREE.Quaternion() | Another way to store a turn, which never gets stuck |
new THREE.Matrix4() | Position, turn and size in one; used by InstancedMesh |
THREE.MathUtils.degToRad(90) | Degrees to radians |
Picking and controls
Explained in 3D functions.
| Name | What it does |
|---|---|
const ray = new THREE.Raycaster() | Makes a picker |
ray.setFromCamera(new THREE.Vector2(x, y), camera) | Aims it through a point, where x and y run from -1 to 1 across and up the canvas: x = … |
const hits = ray.intersectObjects(listOfThings) | What it hits, nearest first |
const controls = new addons.OrbitControls(camera, canvas) | Drag to orbit, pinch or scroll to zoom, two fingers or right-drag to pan |
controls.update() | Call every frame in draw() |
controls.target.set(x, y, z) | The point it orbits round |
controls.enableDamping = true | Glides to a stop when you let go |
controls.autoRotate = true, controls.autoRotateSpeed = 2 | Turns slowly by itself |
controls.minDistance = 2, controls.maxDistance = 20 | How close and how far you can zoom |
controls.maxPolarAngle = Math.PI / 2 | Stops the camera going below the floor |
controls.enableZoom, controls.enablePan, controls.enableRotate | Switch each gesture on or off |
Sprites and hit-testing
Moving pictures that can tell when they touch.
| Name | What it does | More |
|---|---|---|
new Sprite(picture, x, y, size) | A moving picture with x, y, vx, vy, angle, spin, size, visible, update(dt) … | 2D functions |
remove(list, thing) | Take a thing out of a list | 2D functions |
sprite.picture | An emoji or text, an image from loadImage, or a function that draws it | Drawing in 2D |
sprite.x, sprite.y | Where its centre is | Drawing in 2D |
sprite.vx, sprite.vy | Its speed in points per second, used by update(dt) | Drawing in 2D |
sprite.angle | How far it is turned | Drawing in 2D |
sprite.spin | How fast it turns each second, used by update(dt): degrees(180) is half a turn a second | Drawing in 2D |
sprite.size | How big it is, in points (48 unless you say) | Drawing in 2D |
sprite.visible | false hides it | Drawing in 2D |
sprite.update(dt) | Moves it by its speed and turns it by its spin | Drawing in 2D |
sprite.draw() | Draws it (call this in your draw()) | Drawing in 2D |
sprite.touches(other) | true when the two overlap | Drawing in 2D |
sprite.hit(list) | The first sprite in the list that it touches, or null when it touches none | Drawing in 2D |
sprite.contains(x, y) | true when that point is on it | Drawing in 2D |
sprite.shape | "circle" (as it starts) or "box" | Drawing in 2D |
sprite.radius | The size of its circle | Drawing in 2D |
sprite.width, sprite.height | The size of its box | Drawing in 2D |
sprite.wrap() | When it has gone off one edge, it comes back on the opposite one | Drawing in 2D |
sprite.bounce() | Bounces it off the edges | Drawing in 2D |
sprite.offscreen() | true when all of it is outside the picture | Drawing in 2D |
sprite.push(amount) | Speeds it up the way it faces: this is an engine | Drawing in 2D |
sprite.forward(distance) | Steps it the way it faces, without changing its speed | Drawing in 2D |
sprite.limit(speed) | Slows it to that speed if it is going faster | Drawing in 2D |
sprite.angleTo(other) | The angle from it to another sprite, to mouse, or to a point: angleTo(x, y) | Drawing in 2D |
sprite.distanceTo(other) | How far it is to another sprite, to mouse, or to a point: distanceTo(x, y) | Drawing in 2D |
Sprite.box(x, y, width, height, colour) | A coloured box, tested as a box | Drawing in 2D |
Sprite.circle(x, y, size, colour) | A coloured circle size across, tested as that circle | Drawing in 2D |
Keyboard, mouse and touch
What is held now, what went down since the last frame, and functions called when something happens.
Explained in 2D functions.
| Name | What it does |
|---|---|
keys | The set of keys held down: keys.has("ArrowLeft") |
pressed, released | The keys that went down, and came up, since the last frame: pressed.has(" ") |
mouse.x, mouse.y, mouse.down | Where the pointer or finger is, and whether it is pressed |
mouse.button, mouse.inside | Which button is down ("left", "middle", "right" or null), and whether the pointer is … |
mouse.dx, mouse.dy, mouse.wheel | How far the pointer moved, and the wheel turned, since the last frame |
touches | Every finger (or pressed mouse button) that is down: each has id, x, y, startX … |
pinch.scale, pinch.change, pinch.x, pinch.y | Two fingers as a zoom: the scale since the pinch began, its change since the last frame, and … |
Functions you write
Explained in How a program is shaped.
| Name | What it does |
|---|---|
onKeyDown(key, code) | A key is pressed |
onKeyUp(key, code) | A key is let go |
onKeyRepeat(key, code) | A key that is held down repeats, as it does when you type |
onMouseDown(x, y, button) | The mouse button or a finger goes down |
onMouseMove(x, y) | The pointer moves |
onMouseUp(x, y, button) | The button or finger comes up |
onTouchStart(touch) | A finger or a mouse button goes down |
onTouchMove(touch) | A finger that is down moves |
onTouchEnd(touch, cancelled) | A finger comes up |
onWheel(amount) | The wheel turns |
onPinch(scale, change) | Two fingers move together or apart |
Frames and timing
Used with await, in a loop of your own.
| Name | What it does | More |
|---|---|---|
await frame() | Waits for the next frame, so this one is shown | 2D functions |
await flush() | The same as frame(): shows what is drawn so far and carries on at the next frame | 2D functions |
await sleep(seconds) | Waits that long | 2D functions |
await vsync() | Another name for frame(): waits for the screen's next refresh | How a program is shaped |
Saved values
One value under a name, still there the next time.
Explained in Saved values.
| Name | What it does | In Pyctures |
|---|---|---|
save(name, value) | Keeps the value under that name | save |
load(name, otherwise) | Gives back the value saved under that name | load |
Files
A text or JSON file the scene writes and reads back. Real files beside the scene in the app on an iPhone, iPad or Android device and for a saved scene in the desktop app; kept by the browser on the web and in an exported page: where they are kept.
Explained in Files and databases.
| Name | What it does | In Pyctures |
|---|---|---|
await saveText(path, text) | Writes the text as a file | save_text |
await saveJSON(path, value) | Writes a value as a JSON file: a number, text, true or false, a list or an object | save_json |
await loadText(path) | The text of the file | load_text |
await loadJSON(path) | The value in a JSON file, ready to use | load_json |
Databases
Rows in a SQLite database, asked for in SQL. Real files beside the scene in the app on an iPhone, iPad or Android device and for a saved scene in the desktop app; kept by the browser on the web and in an exported page: where they are kept.
Explained in Files and databases.
| Name | What it does | In Pyctures |
|---|---|---|
await openDatabase(name) | Opens the database of that name, making it the first time | open_database |
await db.query(sql, ...values) | Asks a question (select) | db.query |
await db.run(sql, ...values) | Changes the database: create table, insert, update, delete | db.run |
await db.close() | Finishes with the database | db.close |
Other names
| Name | What it does | More |
|---|---|---|
await loadFont(name, path) | Loads a font file beside the scene, ready to use by its name in ctx.font | Tips and limits |
await use(path) | Loads another .js file beside the scene and hands back what it exports | Tips and limits |
measure(name, work) | Times a part of a frame, shown with the frame rate | Finding mistakes |
Image processing
Methods of a picture from loadImage, each used with await: const small = await img.resize({ width: 200 }). They are part of Circuitry, not of the pictures.js library, so they do not work in an exported page or with the library on a page of its own. Some run on any device and some need an Apple device: the badges say which, and Images from Code has every option.
Explained in Images from Code. All of them are In Circuitry only; the badge on each row says which devices.
| Name | What it does | Where it works |
|---|---|---|
removeBackground() | Cut out the main subject; everything else becomes transparent | Apple devicesiOS 17 / macOS 14 or later |
resize({ width, height, percent, fit: "contain" }) | Scale it | Any device |
enhance() | Improve exposure, colour and contrast automatically | Apple devices |
sepia({ intensity: 0.8 }) | Warm brown old-photo tone | Apple devices |
mono() | Black and white | Apple devices |
noir() | High-contrast black and white | Apple devices |
vintage() | Faded, warm film look | Apple devices |
blur({ radius: 10 }) | Soften the whole picture | Apple devices |
sharpen({ radius: 2.5, intensity: 0.5 }) | Crisper edges | Apple devices |
vibrance({ amount: 1 }) | Richer colours, gently | Apple devices |
rotate({ angle: 90, background: "#00000000" }) | Rotate by 90/180/270 or any arbitrary angle | Any device |
flip({ axis: "horizontal" }) | Mirror horizontally, vertically, or both | Any device |
crop({ x: 0, y: 0, width: 256, height: 256 }) | Cut a rectangular region from an image | Any device |
convert({ format: "webp", quality: 0.9 }) | Re-encode as PNG / JPG / WebP / AVIF / HEIC | Any device |
stripMetadata({ keepOrientation: true }) | Remove EXIF / GPS / camera info by re-encoding | Any device |
edgeDetect({ kernel: "sobel", threshold: 80 }) | Sobel / Prewitt / Laplacian edge map | Any device |
watermark({ text: "Sample", anchor: "bottom-right", opacity: 0.75, fontSize: 28, color: "#ffffff" }) | Write text over the picture | Any device |
cannyEdges({ low: 50, high: 150 }) | Hysteresis edge detector — cleaner, connected edges vs the kernel filter | Any device |
threshold({ mode: "otsu", value: 127, invert: false }) | Binarize via fixed value, Otsu (auto), or local adaptive thresholding | Any device |
findContours({ low: 50, high: 150, minArea: 64, overlay: true }) | Detect blobs/shapes; returns exact count + per-region area, bbox, centroid | Any device |
detectShapes({ minArea: 64, epsilon: 0.04, overlay: true }) | Classify each contour as triangle / rectangle / square / circle / polygon | Any device |
findFaces({ overlay: true }) | Count the faces in a photo and return where each one is | Apple devices |
readCodes({ overlay: true }) | Read every QR code and barcode in the picture | Apple devices |
classify({ maxLabels: 10, minConfidence: 0.1 }) | Name what is in the picture (dog, beach, food…) with a confidence for each label | Apple devices |
photoDetails() | Date taken, location, camera and exposure, as data | Apple devices |
hideFaces({ style: "blur" }) | Blur, pixelate or black out every face in the photo | Apple devices |
scanDocument({ enhance: true }) | Find the page in a photo and flatten it to a straight-on scan | Apple devices |
smartCrop({ aspect: "1:1" }) | Crop to the part of the photo that draws the eye | Apple devices |
straighten() | Level a tilted horizon | Apple devices |
faviconSet({ includeIco: true, includeManifest: true }) | Generate web favicons: 16/32/48/192/512 PNGs + apple-touch + favicon.ico + manifest icons | Any device |
appIconSet({ platform: "ios" }) | Generate iOS .appiconset and/or Android mipmap density buckets with Contents.json | Any device |
trace({ colors: 16, detail: "medium" }) | Turn it into flat-colour vector shapes (as 2Vec does): a picture you can draw, with its SVG … | Any device |
save(name) | Write the picture where the scene keeps its files (.png, .jpg or .webp; a traced picture as … | Any device |
run(name, options) | Run any method above by its name | Any device |
available() | The names of the methods this device can run | Any device |
Related
- 2D functions: every 2D function, with pictures and examples
- 3D functions: every 3D function
- How a program is shaped: how a scene is put together