p5.utils

Check OpenProcessing page for live examples to see them in action. You can add the library to your OP project directly from the UI.

p5.utils Library

A set of utilities and additional features for my creative coding class aiming to help students while introducing the algorithmic thinking.

The list of utilities in p5.Utils repository. Click on thumbnails to access examples on p5JS editor;

1_pixelRuler	2_debugView	3_getTimeStamp

4_saveCanvas	5_arrayResize	6_fxShadow

7_GradientFill	8_RadialGradientFill	9_Countdown

How to use p5.Utils library?

Option 1 (Quick Start via P5JS Online Editor)

Navigate to p5JS examples collection.
Click on p5.utils.template.
Hit CMD+s (or File->Save). This will create a copy of required files in your P5JS account. Whenever you need to access p5.utils you can follow the same steps.

Option 2 (If you are using local text editor like VSCode for development)

Download the final minified js version from “Releases” page.
Upload p5.utils.min.js to your project folder in p5 editor.

Include the p5.utils.min.js in the index.html document before p5.js libs as follows;

  <script src="libraries/p5.min.js"></script>
  <script src="libraries/p5.sound.min.js"></script>
  <script src="libraries/p5.utils.min.js"></script>

Declare and initialize the lib before the setup() prefably as follows;
```
  var utils = new p5.Utils();
```
Now you can call any methods defined in p5.utils library using dot notation as follows in setup() or any other custom methods in your code;
```
  utils.enablerRuler(); 
```
Option 3 (Import the lib. using CDN service)

Include CDN source to you ìndex.html.

  <script src="https://cdn.jsdelivr.net/gh/alptugan/p5.utils@latest/src/p5.utils.min.js"></script>

Repeat the above steps 4 and 5.

Reference

p5.Utils extends p5 with several functionalities including cheaper drawingcontext effects, pixel ruler (useful for new commers), array operations, file naming, dom based debug window to avoid rendering text in p5JS.

debug(_itemName)

Create Debug Div cause p5 font is expensive.

getTimeStamp([_date]) ⇒ string

Timestamp function useful for file naming to avoid overwrite issues.

getRandomInt(_min, _max) ⇒ number

Generates and returns a random integer between min and max number

saveCanvas([_prefix=], [_suffix])

Utilizes p5JS saveCanvas function to make it easier file saving process by combining the function with getTimeStamp() method.

arrayResize(_arr, _newSize, [_defaultValue]) ⇒ Array.<number> | Array.<string> | Array.<boolean>

Resizes an array and returns it. Similar to vectors resize in C++.

createGrid(_row, _col, _totalW, _totalH, [_margin], [_type], [_alignX], [_alignY]) ⇒ Object.<number>

Returns an array of object that holds position and size information for each grid element. Fills the grid row by row.

debugGrid([_fz], [_colorTxt], [_colorBorder])

Displays the grid tiles of createGrid and index of each gridItem.

beginShadow(_color, _shadowBlur, _shadowOffsetX, _shadowOffsetY)

Creates shadow effect using drawing context. Must be used with endShadow method. See examples for how to use it.

endShadow()

Clears shadow effect for the following graphics on the canvas. For example usage check beginShadow.

beginRadialGradient(_colorsArr, _startX, _startY, _rad, [_endX], [_endY], [_rOuter], [_ratio])

Default Context 2D Radial Gradient fill style. Must be used with endRadialGradient method. See examples for how to use it. Reference: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createRadialGradient

endRadialGradient()

Stops radial gradient fill for the following graphics on the canvas. For example usage check beginRadialGradient page.

beginLinearGradient(_colorsArr, _startX, _startY, _endX, _endY, [_colorsRatio])

Default Context 2D Gradient fill style. Must be used with endLinearGradient method. See examples for how to use it.

Reference: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createLinearGradient

endLinearGradient()

Stop Gradient fill for the following graphics. Must be used with beginLinearGradient method. See examples for how to use it.

text(_txt, _x, _y, [_size], [_font], [_alignH], [_alighV])

Set the style and display the text in a single method. See getTimeStamp example on how to use the function.

notify(_on_every_nth_second) ⇒ boolean

returns true every nth second in draw function

setRulerStyle([_p5rulerBgColor], [_p5rulerTxtColor], [_p5rulersize], [_p5rulerInfoColor], [_p5rulerInfoBgColor], [_p5rulerTickColor], [_p5rulerFont], [_p5rulerInfoEnable])

Customize the pixel ruler style. Set the colors and font options. Also customizes the debug background and text colors.

disableRuler()

Removes the ruler graphics from the canvas.

enableRuler()

Ruler for newcomers to show pixel meter.

debug(_itemName)

Create Debug Div cause p5 font is expensive.

Kind: global function

Param	Type	Description
_itemName	`Object.<string, number>` \| `Object.<string, string>`	The argument must be in JSON data format. The function automatically parses “keys” to titles and their “values” next to them. You can add as many objects as you want.

Example (How to use debug() method.)

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();

utils.debug(
{
   "FPS": frameRate().toFixed(0),
   "Frequency": frequency.toFixed(3)
});

getTimeStamp([_date]) ⇒ `string`

Timestamp function useful for file naming to avoid overwrite issues.

Kind: global function
Returns: string - Current date + time depending on _date argument value.

When _date = true;

The return format is Year-Month-Day_Hour-Minute-Second

When _date = false;

The return format is Hour-Minute-Second
See: text

Param	Type	Default	Description
[_date]	`boolean`	`true`	If true -> Timestamp within Year-Month-Day

Example

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();

// Font source:
// https://www.dafont.com/lcd-at-t-phone-time-date.font
var cutomFontName = "LCDAT&TPhoneTimeDate.ttf";

function setup() {
  createCanvas(600, 600);
  //noLoop();
}

function draw() {
  background(200);

  // get current time stamp within date
  var currentTime = utils.getTimeStamp();
  //print(currentTime);

  // write it to canvas using utils's text function
  fill(255, 100, 20);
  utils.text(
    currentTime,        // string to display
    width * 0.5 - 100,   // x position
    height * 0.5 - 60,  // y position
    16
  );

  // get current time stamp without date
  var currentTime2 = utils.getTimeStamp(false);
  fill(90, 90, 90);
  // write it to canvas using utils's text function
  utils.text(
    currentTime2,   // string to display
    width * 0.5,   // x position
    height * 0.5,  // y position
    80,            // fontsize
    cutomFontName,  // custom font
    CENTER,        // text alignment horizontal
    CENTER);       // text alignment vertical

}

getRandomInt(_min, _max) ⇒ `number`

Generates and returns a random integer between min and max number

Kind: global function
Returns: number - Result will be integer

Param	Type	Description
_min	`number`	Floor value of the random number
_max	`number`	Ceil value of the random number

saveCanvas([_prefix=], [_suffix])

Utilizes p5JS saveCanvas function to make it easier file saving process by combining the function with getTimeStamp() method.

Kind: global function

Param	Type	Default	Description
[_prefix=]	`string` \| `number`		Any relevant text in the begining of the file name. If it is leaved empty, the file name will be Year-Month-Day_Hour-Minute-Second.PNG
[_suffix]	`string`	`"png"`	The file extension JPG, PNG, …

Example

var x, y, px, py;
var jump = 10;
var ptime = 2000;

// Init global utils var
var utils = new p5.Utils();
var counter = 0;

function setup() {
  createCanvas(600, 600);

  x = width * 0.5;
  y = height * 0.5;
  px = x;
  py = y;
  background(180);
}

function draw() {
  //background(180, 1);
  px = x;
  py = y;


  // Basic random walker algorithm
  var dice = random();

  if (dice < 0.25) {
    x += jump;
  } else if (dice < 0.5) {
    x -= jump;
  } else if (dice < 0.75) {
    y += jump;
  } else {
    y -= jump;
  }

  strokeWeight(5);
  stroke("#ffcc00");
  noFill();
  beginShape();
  vertex(x, y);
  vertex(px, py);
  endShape();

  // Automated saveCanvas for every 10th second
  if (utils.notify(10) == true && counter < 4) {
    ptime = millis();

    // save current canvas image with default attributes
    utils.saveCanvas();

    // or you can set prefix and file extension argument
    // utils.saveCanvas("randomWalker","jpg");

    // clear the canvas again
    background(180);


    // set starting position to middle of the canvas
    x = width * 0.5;
    y = height * 0.5;
    px = x;
    py = y;

    counter++;
  }

}

arrayResize(_arr, _newSize, [_defaultValue]) ⇒ `Array.<number>` | `Array.<string>` | `Array.<boolean>`

Resizes an array and returns it. Similar to vectors resize in C++.

Kind: global function
Returns: Array.<number> | Array.<string> | Array.<boolean> - The new array

Param	Type	Default	Description
_arr	`Array.<number>` \| `Array.<string>` \| `Array.<boolean>`		The array to be resized
_newSize	`number`		The new size of the array
[_defaultValue]	`number` \| `string` \| `boolean`	`-1`	Default value for all members of the new array.

Example

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();
var arr = [];
arr = utils.arrayResize(arr,10);
print(arr);

// or assign default values
arr = utils.arrayResize(arr, 22, random(0,1));
print(arr);

createGrid(_row, _col, _totalW, _totalH, [_margin], [_type], [_alignX], [_alignY]) ⇒ `Object.<number>`

Returns an array of object that holds position and size information for each grid element. Fills the grid row by row.

Kind: global function
Returns: Object.<number> - The returned object includes {x,y,w,h}

Param	Type	Default	Description
_row	`number`		Number of rows
_col	`number`		Number of columns
_totalW	`number`		The width of total grid space
_totalH	`number`		The height of total grid space
[_margin]	`number`	`0`	Gap between each grid element
[_type]	`const`	`GRID.SQUARE`	The w/h ratio of the each grid. If you want to create rectangular grids you can use `GRID.RECT`
[_alignX]	`boolean`	`false`	Alignment on the x-axis according to the width of the canvas
[_alignY]	`boolean`	`false`	Alignment on the y-axis according to the height of the canvas

Example

// Coming soon... to do

debugGrid([_fz], [_colorTxt], [_colorBorder])

Displays the grid tiles of createGrid and index of each gridItem.

Kind: global function

Param	Type	Default	Description
[_fz]	`Number`	`10`	Id font-size.
[_colorTxt]	`p5.Color`	`color(0)`	Id Text Color.
[_colorBorder]	`p5.Color`	`color(0,200)`	Grid Color.

beginShadow(_color, _shadowBlur, _shadowOffsetX, _shadowOffsetY)

Creates shadow effect using drawing context. Must be used with endShadow method. See examples for how to use it.

Kind: global function

Param	Type	Description
_color	`p5.Color` \| `string`	The color can be declared as `color(r,g,b,a)` or in hexadecimal format `"#FFCC00"` as string argument.
_shadowBlur	`number`	Blur amount of the shadow.
_shadowOffsetX	`number`	Shadow offset for x axis.
_shadowOffsetY	`number`	Shadow offset for y axis.

Example

var utils = new p5.Utils();
function setup() {
     createCanvas(400,400);
     rectMode(CENTER);
}

function draw() {
     utils.beginShadow("#000000", 5, 10, 10);
     rect(width*0.5, height*0.5, 100, 100);
     utils.endShadow();
}

endShadow()

Clears shadow effect for the following graphics on the canvas. For example usage check beginShadow.

Kind: global function
See: beginShadow

beginRadialGradient(_colorsArr, _startX, _startY, _rad, [_endX], [_endY], [_rOuter], [_ratio])

Kind: global function

Param	Type	Default	Description
_colorsArr	`Array.<p5.Color>` \| `Array.<string>`		List of colors in the gradient fill.
_startX	`number`		The x-axis coordinate of the start point.
_startY	`number`		The y-axis coordinate of the start point.
_rad	`number`		Radius of the first radiant gradient space.
[_endX]	`number`	`-1`	The x-axis coordinate of the end point. If you leave it as -1, the function set _endX=_startX.
[_endY]	`number`	`-1`	The y-axis coordinate of the end point. If you leave it as -1, the function set _endY=_startY
[_rOuter]	`number`	`-1`	Radius of the outer radiant gradient space. If you leave it as -1, the function set _rOuter=_rad and _rad=_rad*0.1
[_ratio]	`number`	`-1`	The distribution weight of colors. The values must be between 0 - 1. Conventionally, if you include three colors, set the first one to 0, the last one to 1, and the middle one depends on your choice(0-1). The method automatically assign start and stop values, if you do not specify any value they will be generated randomly.

Example

// Declare global utils var
var utils = new p5.Utils();
function setup() {
     createCanvas(innerWidth, innerHeight);
}

function draw() {
 background(200);
 utils.beginRadialGradient(
     ["#ffcc00","#ccff00","#ff0000"],
     width*0.5,
     height*0.5,
     100,
     width*0.5 + 100,
     height*0.5 + 100,
     400);
 circle(width*0.5, height*0.5,400);
 utils.endRadialGradient();

}

endRadialGradient()

Stops radial gradient fill for the following graphics on the canvas. For example usage check beginRadialGradient page.

Kind: global function
See: beginRadialGradient

beginLinearGradient(_colorsArr, _startX, _startY, _endX, _endY, [_colorsRatio])

Default Context 2D Gradient fill style. Must be used with endLinearGradient method. See examples for how to use it.

Reference: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createLinearGradient

Kind: global function

Param	Type	Default	Description
_colorsArr	`Array.<p5.Color>` \| `Array.<string>`		List of colors in the gradient fill.
_startX	`number`		The x-axis coordinate of the start point.
_startY	`number`		The y-axis coordinate of the start point.
_endX	`number`		The x-axis coordinate of the end point.
_endY	`number`		The y-axis coordinate of the end point.
[_colorsRatio]	`Array.<number>`	`[]`	The distribution weight of colors. The values must be between 0 - 1. Conventionally, if you include three colors, set the first one to 0, the last one to 1, and the middle one depends on your choice(0-1). The method automatically assign start and stop values, if you do not specify any value they will be generated randomly.

Example

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();

function setup() {
  createCanvas(600, 600);
  noLoop();
}

function draw() {

  background(220);

  noStroke();

  // Begin gradient fill
  utils.beginLinearGradient(
    ["#FFCC00", color(34, 116, 165), color(126, 161, 114)],//Colors
    width * 0.5 - 100,    // gradient begin point x
    height * 0.5 - 100,   // gradient begin point y
    width * 0.5 + 100,    // gradient end point x
    height * 0.5 + 100,   // gradient end point y
    [0, 0.5, 1]           // Position of each color.
  );

  circle(width * 0.5, height * 0.5, 400);

  // End gradient fill
  utils.endLinearGradient();
}

function keyPressed() {
  if (key == 's')
    utils.saveCanvas("linearGradientFill");
}

endLinearGradient()

Stop Gradient fill for the following graphics. Must be used with beginLinearGradient method. See examples for how to use it.

Kind: global function
See: For example usage beginLinearGradient page.

text(_txt, _x, _y, [_size], [_font], [_alignH], [_alighV])

Set the style and display the text in a single method. See getTimeStamp example on how to use the function.

Kind: global function

Param	Type	Default	Description
_txt	`string` \| `number`		Text or number to be displayed
_x	`number`		X position of the text
_y	`number`		Y position of the text
[_size]	`number`	`12`	Font size
[_font]	`string`	`"sans-serif"`	Custom Font face. See example getTimeStamp
[_alignH]	`Constant`	`LEFT`	Text horizontal align
[_alighV]	`Constant`	`TOP`	Text vertical align

notify(_on_every_nth_second) ⇒ `boolean`

returns true every nth second in draw function

Kind: global function
See: saveCanvas method for the example.

Param	Type	Description
_on_every_nth_second	`number`	Set notifier frequency. The input value needs to be in seconds.

Example

if (utils.notify(10) == true) {
     // do something here.
}

setRulerStyle([_p5rulerBgColor], [_p5rulerTxtColor], [_p5rulersize], [_p5rulerInfoColor], [_p5rulerInfoBgColor], [_p5rulerTickColor], [_p5rulerFont], [_p5rulerInfoEnable])

Customize the pixel ruler style. Set the colors and font options. Also customizes the debug background and text colors.

Kind: global function
See: enableRuler

Param	Type	Default	Description
[_p5rulerBgColor]	`string`	`"rgba(30,30,30,1)"`	Pixel Ruler Background color.
[_p5rulerTxtColor]	`string`	`"rgba(150,150,150,1)"`	Text Color on the Pixel Puler.
[_p5rulersize]	`number`	`20`	Ruler size for top and left sides.
[_p5rulerInfoColor]	`string`	`"rgba(30,30,30,1)"`	Info Text Color following the mouse cursor.
[_p5rulerInfoBgColor]	`string`	`"rgba(255,255,255,0.5)"`	Info Text Background color.
[_p5rulerTickColor]	`string`	`"rgba(255,0,0,1)"`	Ticker Color that projects the mouse cursor on top and left ruler bar.
[_p5rulerFont]	`string`	`"11px monospace"`	Overall font size and font-family of the Pixel Ruler.
[_p5rulerInfoEnable]	`boolean`	`true`	Show / hide info text nect to mouse cursor

Example

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();

function setup() {
     createCanvas(400,400);

     // Set styling before the enabling the ruler
     utils.setRulerStyle(
         "rgba(200,200,200,1)", // Ruler Bg Color
         "rgba(30,30,30,1)",    // Ruler Text Color
         20,                    // Ruler Size
         "rgba(200,200,200,1)", // Info Text Color following the mouse cursor
         "rgba(5,5,5,0.7)",     // Info Text Background Color
         "rgba(0,255,0,1)",     // Ticker Color that projects the mouse cursor on top and left ruler bar
         "10px monospace",      // Overall font size and font family
         false                  // Display info card next to cursor. By default it's true
     );

     // No need to run in draw function
     // The function creates its canvases in a different drawing context
     utils.enableRuler();
}

function draw() {
     background(220);
     rect(width*0.5, height*0.5,500, 500);
}

function keyPressed() {
     if(key == 'h') {
         utils.disableRuler();
     }
}

disableRuler()

Removes the ruler graphics from the canvas.

Kind: global function
See: For example usage enableRuler page.

enableRuler()

Ruler for newcomers to show pixel meter.

Kind: global function
See: disableRuler
Example

// Define global variable and initialize p5.Utils lib
var utils = new p5.Utils();

function setup() {
     createCanvas(400,400);

     // No need to run in draw function
     // The function creates its canvases in a different drawing context
     utils.enableRuler();
}

function draw() {
     background(220);
     rect(width*0.5, height*0.5,500, 500);
}

function keyPressed() {
     if(key == 'h') {
         utils.disableRuler();
     }
}

This site is open source. Improve this page.

p5.utils

Check OpenProcessing page for live examples to see them in action. You can add the library to your OP project directly from the UI.

p5.utils Library

The list of utilities in p5.Utils repository. Click on thumbnails to access examples on p5JS editor;

How to use p5.Utils library?

Option 1 (Quick Start via P5JS Online Editor)

Option 2 (If you are using local text editor like VSCode for development)

Option 3 (Import the lib. using CDN service)

Reference

debug(_itemName)

getTimeStamp([_date]) ⇒ string

getRandomInt(_min, _max) ⇒ number

saveCanvas([_prefix=], [_suffix])

arrayResize(_arr, _newSize, [_defaultValue]) ⇒ Array.<number> | Array.<string> | Array.<boolean>

createGrid(_row, _col, _totalW, _totalH, [_margin], [_type], [_alignX], [_alignY]) ⇒ Object.<number>

debugGrid([_fz], [_colorTxt], [_colorBorder])

beginShadow(_color, _shadowBlur, _shadowOffsetX, _shadowOffsetY)

endShadow()

beginRadialGradient(_colorsArr, _startX, _startY, _rad, [_endX], [_endY], [_rOuter], [_ratio])

endRadialGradient()

beginLinearGradient(_colorsArr, _startX, _startY, _endX, _endY, [_colorsRatio])

endLinearGradient()

text(_txt, _x, _y, [_size], [_font], [_alignH], [_alighV])

notify(_on_every_nth_second) ⇒ boolean

setRulerStyle([_p5rulerBgColor], [_p5rulerTxtColor], [_p5rulersize], [_p5rulerInfoColor], [_p5rulerInfoBgColor], [_p5rulerTickColor], [_p5rulerFont], [_p5rulerInfoEnable])

disableRuler()

enableRuler()

getTimeStamp([_date]) ⇒ `string`

getRandomInt(_min, _max) ⇒ `number`

arrayResize(_arr, _newSize, [_defaultValue]) ⇒ `Array.<number>` | `Array.<string>` | `Array.<boolean>`

createGrid(_row, _col, _totalW, _totalH, [_margin], [_type], [_alignX], [_alignY]) ⇒ `Object.<number>`

notify(_on_every_nth_second) ⇒ `boolean`