Skip to content

Latest commit

 

History

History
637 lines (511 loc) · 26.4 KB

README.md

File metadata and controls

637 lines (511 loc) · 26.4 KB
Raw

License: MIT

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)

  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>
  1. 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])

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

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