Images in p5.js

As you would expect, p5.js allows developers to bring in external image files to be used in sketches. These could be backgrounds, foregrounds, replace objects like ellipses, or be used for sprite-based animations.

One issue with loading images in p5, is that it can take time for an image to get loaded. (Sometimes, a long time depending on the size of the file) Therefore, there is a new function we need to learn first called preload().

preload()

• preload() documentation

The preload() function is executed by the p5 engine before the setup() function. It can be used to load files and data. It will block the execution of setup() until all files have been successfully loaded.

The preload() function therefor is, in many ways, equivalent to setup() and draw() in that it is a pseudo-structure function used to define order of execution of p5.js code. Also, like setup() and draw() you will prepend it with the function definition keyword so that the JavaScript interpreter knows you are defining a function that it can call.

// executed first. Must finish all load commands.
function preload(){
    // code to load stuff here
}

// executed second, will prepare the sketch.
function setup(){
    // setup code here
}

// the draw loop.
function draw(){
    // draw code here
}

Loading an Image

To load an image, we need to do a couple of things.

1. Define a variable namespace in the global scope to store a reference to the image.
   • This should be defined outside of preload() so that it is available inside of the setup() and draw() functions later on.
2. Load the image with the loadImage() function, inside of the preload() function.
3. Pass a reference to this image to the variable namespace defined above.

The loadImage() function takes a string as its sole input parameter. This string should represent either a relative or absolute URL path to the image file you wish to load.

The return of the loadImage() function should be passed to the variable initially defined.

let img;

function preload(){
    img = loadImage('images/myAwesomeImage.jpg');
}

Using an Image

To use an image, we need to pass the image reference bound to the variable to the image() function.

• image() documentation

This function takes three parameters at minimum, with additional options provided through additional parameters.

When only supplying three parameters, the first parameter is the reference to the image. The second and third parameter are the location to place the top-left corner of the image on the canvas. So for example;

image(img, 0, 0);

The above would draw an image at location 0, 0 in the canvas with whatever image was referenced from the img variable.

Let’s look at a full example.

NOTE: For the following examples, we will assume the following directory structure.

/01_image_p5Example
├── images
│   └── happyMusick.jpg
├── index.html
├── p5_lib
│   └── p5.min.js
├── readme.md
└── sketch.js

Therefore, our code could look like;

Specify the Size of an Image

When only three input parameters are supplied, then the size of the image on the canvas is the size of the actual image file. (i.e. if the image is 500 pixels wide, then the displayed imaged will 500 pixels wide)

When you supply five parameters to the image() function, the fourth and fifth parameters allow developers to specify the size of the image on the canvas.

As an example, the following sketch is the same as the one above, except that the image is being presented 50px wide and 500px heigh.

Moving Images

I believe this goes without saying, but just in case, since we can supply the position information to the image() function, it also means that images can be moved around the canvas.

Images for Background

We can also pass an image reference to the background() function. When you pass an image reference to the background() function p5 uses the image as the background of the canvas.

p5 will stretch an image to fit the background. So either set the canvas size when using images for backgrounds, or choose images that will look good regardless of whether they are stretched or not.