Image

Why don't we see more interactive and experimental plays with images, even as photos, videos and gifs fill the web? Perhaps working with images on html canvas is way harder than it should be — even a common use case, like loading an image and getting the color values of its pixels, proves to be practically tortuous.

Fret not! Pts' Img provides some convenient and straightforward functions to help you experiment with images. Let's take a look.

Loading and Displaying Images

Let's start a minimalistic example: Load an image and display it on canvas. This can be done in 3 lines of code:

const run = Pts.quickStart( "#elemID" );
const img = Img.load( "/assets/demo.jpg" );
run( t => form.image( space.pointer, img ) );

js:image_load

Image credit: "C 50 Last Birds And Flowers" by Kurt Schwitters

The above example uses the static function load to load an image, and then uses CanvasForm's image function to display it automatically when it's loaded.

If you need to manually track when the image is loaded, you can either:

access the img.loaded property
add a callback function to the Img.load function
create an Img instance, call its load function and use async/await.

const img = new Img();
await img.load( "/assets/demo.jpg" )

Once the image is loaded, you can access its properties like width and height and manipulate its data. We will be discussing these advanced use cases next.

js:image_load2

Once the image is loaded, we can access its original width and height, and rescale it to fit the canvas size.

Editing Images

When you create an Img instance with its editable parameter set to true, it will hold an internal canvas to support image manipulations. It also supports higher pixel-density displays via the pixelScale parameter. An example:

// Create an editable img with the current space's pixelScale
let img = new Img( true, space.pixelScale );
img.load( "/assets/demo.jpg" );

// Alternatively, use the Img.load static function
let img2 = Img.load( "/assets/demo.jpg", true, space.pixelScale );

With an editable image, you can now inspect and manipulate it creatively.

Get Pixels and Crop Regions

The pixel function supports a very common use case: specify a pixel position on the image, get its RGBA color values, and do something with it. A wide range of visual possibilities may open up if you use this simple function creatively.

js:image_pixel

Try scribbling in different regions of the image to change it. This demo combines `Create.delaunay` with `Img.pixel`.

Another common use case is to crop a region of the image. The crop function takes a bounding box and returns an ImageData. You can then use CanvasForm'simageData to draw the region.

form.imageData( img.crop( bound ) );

Let's try this in a demo:

js:image_crop

Click to cut out a region in the image. Move pointer to shift its position.

It's more efficient to draw ImageData directly on canvas. If needed, you can also export it to a blob using Img.imageDataToBlob and then load it into an image again.

Edit and Sync

Since an editable Img stores an internal canvas, you can leverage CanvasForm's many drawing functions to draw directly on it. It's that easy!

After the image is loaded, you can access the canvas' rendering context through the property img.ctx and then create a new CanvasForm instance with it. For example:

let form;
img.load( "demo.jpg" ).then( a => form = new CanvasForm(a.ctx) )

js:image_edit

Move pointer to draw patches on the image.

Additionally, the filter function supports image filter effects like desaturation and blur (See the full list supported by canvas). Note that some effects may not work in mobile browsers.

img.filter( "blur(10px) contrast(20%) saturate(0%)" )

To display the edited image, use CanvasForm's image function but pass img.canvas (instead of img itself) in the parameter. As we are only editing an internal canvas, the original image is unchanged until it's explicitly updated. Use sync to update the original image when needed.

Tips and Tricks

Anticipate screens with different pixel density. You can pass a CanvasSpace's pixelScale when creating an Img instance. (See example in Cheatsheet below)
You can load an image from a base64 string or an url, or from a blob via the fromBlob function. To export the current image, use toBase64 or toBlob functions.
CanvasForm's image drawing function can take either an Img instance or a CanvasImageSource which includes various kinds of image objects like HTML Image or Canvas.
Typically, you can't load an image from another domain due to security concerns. But if the image server allows for it and you want to do it, you can set the crossOrigin parameter to true when creating an Img instance. More details here.

Cheatsheet

Creating, loading, displaying

// Simplest way
let img = Img.load( "demo.jpg");

// Load an editable image that matches the screen's resolution
// with an optional callback function when the image is loaded.
let img = Img.load("demo.png", true, space.pixelScale, onLoad );

// Equivalent but using async/await
let img = new Img( true, space.pixelScale );
await img.load("demo.png")

// Display an image automatically when it's loaded 
form.image( [0,0], img );

// Check if image is loaded, then display its canvas in a rect
if (img.loaded) form.image( rect, img.canvas );

Useful properties

img.loaded; // true if the image is loaded
img.image; // the original image
img.canvas; // the internal canvas of an editable Img
img.ctx; // the context which can be used to create a CanvasForm

Editing an image

img.crop( rect )
img.resize( 0.5, true );
img.filter( "blur(10px) | contrast(200%)" );
img.pixel( space.pointer );

// Draw on image
let imgForm = new CanvasForm( img.ctx );
imgForm.fill( "#f00" ).point( space.pointer, 20 );

// Export as base64 string
img.toBase64();