p5.utils

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)

1. Navigate to p5JS examples collection.
2. Click on p5.utils.template.
3. 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)

1. Download the final minified js version from "Releases" page.

2. Upload p5.utils.min.js to your project folder in p5 editor.

3. 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>
   

4. Declare and initialize the lib before the setup() prefably as follows;

   var utils = new p5.Utils();
   

5. 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)

1. Include CDN source to you ìndex.html.

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

2. Repeat the above steps 4 and 5.

Reference

p5.Utils library

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.

Functions

debug(_itemName)

Create Debug Div cause p5 font is expensive.

getTimeStamp([_date]) ⇒ String

Timestamp function useful for file naming to avoid overwrite issues.

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++.

beginShadow(_color, _shadowBlur, _shadowOffsetX, _shadowOffsetY)

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

endShadow()

Stops shadow effect for the following graphics on the canvas. For example usage beginShadow 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

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

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

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

}

saveCanvas([_prefix], [_suffix])

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

Kind: global function

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

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);

beginShadow(_color, _shadowBlur, _shadowOffsetX, _shadowOffsetY)

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

Kind: global function

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()

Stops shadow effect for the following graphics on the canvas. For example usage beginShadow page.

Kind: global function
See: For example usage beginShadow 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

Kind: global function

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

notify(_on_every_nth_second) ⇒ boolean

returns true every nth second in draw function

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

Example

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

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();
     }
}