diff --git a/src/math/trigonometry.js b/src/math/trigonometry.js index 4927bb8d2c..51f42d71a9 100644 --- a/src/math/trigonometry.js +++ b/src/math/trigonometry.js @@ -16,9 +16,11 @@ import * as constants from '../core/constants'; p5.prototype._angleMode = constants.RADIANS; /** - * The inverse of cos(), returns the arc cosine of a - * value. This function expects arguments in the range -1 to 1. By default, - * `acos()` returns values in the range 0 to π (about 3.14). If the + * Calculates the arc cosine of a number. + * + * `acos()` is the inverse of cos(). It expects + * arguments in the range -1 to 1. By default, `acos()` returns values in the + * range 0 to π (about 3.14). If the * angleMode() is `DEGREES`, then values are * returned in the range 0 to 180. * @@ -29,27 +31,45 @@ p5.prototype._angleMode = constants.RADIANS; * @example *
* - * let a = PI; - * let c = cos(a); - * let ac = acos(c); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(c, 3)}`, 35, 50); - * text(`${round(ac, 3)}`, 35, 75); - * - * describe('The numbers 3.142, -1, and 3.142 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate cos() and acos() values. + * let a = PI; + * let c = cos(a); + * let ac = acos(c); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(c, 3)}`, 35, 50); + * text(`${round(ac, 3)}`, 35, 75); + * + * describe('The numbers 3.142, -1, and 3.142 written on separate rows.'); + * } * *
* *
* - * let a = PI + QUARTER_PI; - * let c = cos(a); - * let ac = acos(c); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(c, 3)}`, 35, 50); - * text(`${round(ac, 3)}`, 35, 75); - * - * describe('The numbers 3.927, -0.707, and 2.356 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate cos() and acos() values. + * let a = PI + QUARTER_PI; + * let c = cos(a); + * let ac = acos(c); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(c, 3)}`, 35, 50); + * text(`${round(ac, 3)}`, 35, 75); + * + * describe('The numbers 3.927, -0.707, and 2.356 written on separate rows.'); + * } * *
*/ @@ -58,11 +78,12 @@ p5.prototype.acos = function(ratio) { }; /** - * The inverse of sin(), returns the arc sine of a - * value. This function expects input values in the range of -1 to 1. By - * default, `asin()` returns values in the range -π ÷ 2 - * (about -1.57) to π ÷ 2 (about 1.57). If the - * angleMode() is `DEGREES` then values are + * Calculates the arc sine of a number. + * + * `asin()` is the inverse of sin(). It expects input + * values in the range of -1 to 1. By default, `asin()` returns values in the + * range -π ÷ 2 (about -1.57) to π ÷ 2 (about 1.57). If + * the angleMode() is `DEGREES` then values are * returned in the range -90 to 90. * * @method asin @@ -72,27 +93,45 @@ p5.prototype.acos = function(ratio) { * @example *
* - * let a = PI / 3; - * let s = sin(a); - * let as = asin(s); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(s, 3)}`, 35, 50); - * text(`${round(as, 3)}`, 35, 75); - * - * describe('The numbers 1.047, 0.866, and 1.047 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate sin() and asin() values. + * let a = PI / 3; + * let s = sin(a); + * let as = asin(s); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(s, 3)}`, 35, 50); + * text(`${round(as, 3)}`, 35, 75); + * + * describe('The numbers 1.047, 0.866, and 1.047 written on separate rows.'); + * } * *
* *
* - * let a = PI + PI / 3; - * let s = sin(a); - * let as = asin(s); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(s, 3)}`, 35, 50); - * text(`${round(as, 3)}`, 35, 75); - * - * describe('The numbers 4.189, -0.866, and -1.047 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate sin() and asin() values. + * let a = PI + PI / 3; + * let s = sin(a); + * let as = asin(s); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(s, 3)}`, 35, 50); + * text(`${round(as, 3)}`, 35, 75); + * + * describe('The numbers 4.189, -0.866, and -1.047 written on separate rows.'); + * } * *
*/ @@ -101,12 +140,13 @@ p5.prototype.asin = function(ratio) { }; /** - * The inverse of tan(), returns the arc tangent of a - * value. This function expects input values in the range of -Infinity to - * Infinity. By default, `atan()` returns values in the range -π ÷ 2 - * (about -1.57) to π ÷ 2 (about 1.57). If the - * angleMode() is `DEGREES` then values are - * returned in the range -90 to 90. + * Calculates the arc tangent of a number. + * + * `atan()` is the inverse of tan(). It expects input + * values in the range of -Infinity to Infinity. By default, `atan()` returns + * values in the range -π ÷ 2 (about -1.57) to π ÷ 2 + * (about 1.57). If the angleMode() is `DEGREES` + * then values are returned in the range -90 to 90. * * @method atan * @param {Number} value value whose arc tangent is to be returned. @@ -115,27 +155,45 @@ p5.prototype.asin = function(ratio) { * @example *
* - * let a = PI / 3; - * let t = tan(a); - * let at = atan(t); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(t, 3)}`, 35, 50); - * text(`${round(at, 3)}`, 35, 75); - * - * describe('The numbers 1.047, 1.732, and 1.047 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate tan() and atan() values. + * let a = PI / 3; + * let t = tan(a); + * let at = atan(t); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(t, 3)}`, 35, 50); + * text(`${round(at, 3)}`, 35, 75); + * + * describe('The numbers 1.047, 1.732, and 1.047 written on separate rows.'); + * } * *
* *
* - * let a = PI + PI / 3; - * let t = tan(a); - * let at = atan(t); - * text(`${round(a, 3)}`, 35, 25); - * text(`${round(t, 3)}`, 35, 50); - * text(`${round(at, 3)}`, 35, 75); - * - * describe('The numbers 4.189, 1.732, and 1.047 written on separate rows.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Calculate tan() and atan() values. + * let a = PI + PI / 3; + * let t = tan(a); + * let at = atan(t); + * + * // Display the values. + * text(`${round(a, 3)}`, 35, 25); + * text(`${round(t, 3)}`, 35, 50); + * text(`${round(at, 3)}`, 35, 75); + * + * describe('The numbers 4.189, 1.732, and 1.047 written on separate rows.'); + * } * *
*/ @@ -144,15 +202,17 @@ p5.prototype.atan = function(ratio) { }; /** - * Calculates the angle formed by a specified point, the origin, and the - * positive x-axis. By default, `atan2()` returns values in the range + * Calculates the angle formed by a point, the origin, and the positive + * x-axis. + * + * `atan2()` is most often used for orienting geometry to the mouse's + * position, as in `atan2(mouseY, mouseX)`. The first parameter is the point's + * y-coordinate and the second parameter is its x-coordinate. + * + * By default, `atan2()` returns values in the range * -π (about -3.14) to π (3.14). If the * angleMode() is `DEGREES`, then values are - * returned in the range -180 to 180. The `atan2()` function is most often - * used for orienting geometry to the mouse's position. - * - * Note: The y-coordinate of the point is the first parameter and the - * x-coordinate is the second parameter. + * returned in the range -180 to 180. * * @method atan2 * @param {Number} y y-coordinate of the point. @@ -162,17 +222,55 @@ p5.prototype.atan = function(ratio) { * @example *
* + * function setup() { + * createCanvas(100, 100); + * + * describe('A rectangle at the top-left of the canvas rotates with mouse movements.'); + * } + * * function draw() { * background(200); - * translate(width / 2, height / 2); - * let x = mouseX - width / 2; - * let y = mouseY - height / 2; - * let a = atan2(y, x); + * + * // Calculate the angle between the mouse + * // and the origin. + * let a = atan2(mouseY, mouseX); + * + * // Rotate. * rotate(a); - * rect(-30, -5, 60, 10); + * + * // Draw the shape. + * rect(0, 0, 60, 10); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); * * describe('A rectangle at the center of the canvas rotates with mouse movements.'); * } + * + * function draw() { + * background(200); + * + * // Translate the origin to the center. + * translate(50, 50); + * + * // Get the mouse's coordinates relative to the origin. + * let x = mouseX - 50; + * let y = mouseY - 50; + * + * // Calculate the angle between the mouse and the origin. + * let a = atan2(y, x); + * + * // Rotate. + * rotate(a); + * + * // Draw the shape. + * rect(-30, -5, 60, 10); + * } * *
*/ @@ -181,10 +279,11 @@ p5.prototype.atan2 = function(y, x) { }; /** - * Calculates the cosine of an angle. `cos()` is useful for many geometric - * tasks in creative coding. The values returned oscillate between -1 and 1 - * as the input angle increases. `cos()` takes into account the current - * angleMode. + * Calculates the cosine of an angle. + * + * `cos()` is useful for many geometric tasks in creative coding. The values + * returned oscillate between -1 and 1 as the input angle increases. `cos()` + * takes into account the current angleMode(). * * @method cos * @param {Number} angle the angle. @@ -193,42 +292,65 @@ p5.prototype.atan2 = function(y, x) { * @example *
* + * function setup() { + * createCanvas(100, 100); + * + * describe('A white ball on a string oscillates left and right.'); + * } + * * function draw() { * background(200); * - * let t = frameCount; - * let x = 30 * cos(t * 0.05) + 50; + * // Calculate the coordinates. + * let x = 30 * cos(frameCount * 0.05) + 50; * let y = 50; + * + * // Draw the oscillator. * line(50, y, x, y); * circle(x, y, 20); - * - * describe('A white ball on a string oscillates left and right.'); * } * *
* *
* + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * describe('A series of black dots form a wave pattern.'); + * } + * * function draw() { + * // Calculate the coordinates. * let x = frameCount; * let y = 30 * cos(x * 0.1) + 50; - * point(x, y); * - * describe('A series of black dots form a wave pattern.'); + * // Draw the point. + * point(x, y); * } * *
* *
* - * function draw() { - * let t = frameCount; - * let x = 30 * cos(t * 0.1) + 50; - * let y = 10 * sin(t * 0.2) + 50; - * point(x, y); + * function setup() { + * createCanvas(100, 100); + * + * background(200); * * describe('A series of black dots form an infinity symbol.'); * } + * + * function draw() { + * // Calculate the coordinates. + * let x = 30 * cos(frameCount * 0.1) + 50; + * let y = 10 * sin(frameCount * 0.2) + 50; + * + * // Draw the point. + * point(x, y); + * } * *
*/ @@ -237,10 +359,11 @@ p5.prototype.cos = function(angle) { }; /** - * Calculates the sine of an angle. `sin()` is useful for many geometric tasks - * in creative coding. The values returned oscillate between -1 and 1 as the - * input angle increases. `sin()` takes into account the current - * angleMode. + * Calculates the sine of an angle. + * + * `sin()` is useful for many geometric tasks in creative coding. The values + * returned oscillate between -1 and 1 as the input angle increases. `sin()` + * takes into account the current angleMode(). * * @method sin * @param {Number} angle the angle. @@ -249,42 +372,65 @@ p5.prototype.cos = function(angle) { * @example *
* + * function setup() { + * createCanvas(100, 100); + * + * describe('A white ball on a string oscillates up and down.'); + * } + * * function draw() { * background(200); * - * let t = frameCount; + * // Calculate the coordinates. * let x = 50; - * let y = 30 * sin(t * 0.05) + 50; - * line(x, 50, x, y); - * circle(x, y, 20); + * let y = 30 * sin(frameCount * 0.05) + 50; * - * describe('A white ball on a string oscillates up and down.'); + * // Draw the oscillator. + * line(50, y, x, y); + * circle(x, y, 20); * } * *
* *
* + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * describe('A series of black dots form a wave pattern.'); + * } + * * function draw() { + * // Calculate the coordinates. * let x = frameCount; * let y = 30 * sin(x * 0.1) + 50; - * point(x, y); * - * describe('A series of black dots form a wave pattern.'); + * // Draw the point. + * point(x, y); * } * *
* *
* - * function draw() { - * let t = frameCount; - * let x = 30 * cos(t * 0.1) + 50; - * let y = 10 * sin(t * 0.2) + 50; - * point(x, y); + * function setup() { + * createCanvas(100, 100); + * + * background(200); * * describe('A series of black dots form an infinity symbol.'); * } + * + * function draw() { + * // Calculate the coordinates. + * let x = 30 * cos(frameCount * 0.1) + 50; + * let y = 10 * sin(frameCount * 0.2) + 50; + * + * // Draw the point. + * point(x, y); + * } * *
*/ @@ -293,10 +439,12 @@ p5.prototype.sin = function(angle) { }; /** - * Calculates the tangent of an angle. `tan()` is useful for many geometric - * tasks in creative coding. The values returned range from -Infinity - * to Infinity and repeat periodically as the input angle increases. `tan()` - * takes into account the current angleMode. + * Calculates the tangent of an angle. + * + * `tan()` is useful for many geometric tasks in creative coding. The values + * returned range from -Infinity to Infinity and repeat periodically as the + * input angle increases. `tan()` takes into account the current + * angleMode(). * * @method tan * @param {Number} angle the angle. @@ -305,12 +453,21 @@ p5.prototype.sin = function(angle) { * @example *
* + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * describe('A series of identical curves drawn with black dots. Each curve starts from the top of the canvas, continues down at a slight angle, flattens out at the middle of the canvas, then continues to the bottom.'); + * } + * * function draw() { + * // Calculate the coordinates. * let x = frameCount; * let y = 5 * tan(x * 0.1) + 50; - * point(x, y); * - * describe('A series of identical curves drawn with black dots. Each curve starts from the top of the canvas, continues down at a slight angle, flattens out at the middle of the canvas, then continues to the bottom.'); + * // Draw the point. + * point(x, y); * } * *
@@ -320,12 +477,14 @@ p5.prototype.tan = function(angle) { }; /** - * Converts an angle measurement in radians to its corresponding value in - * degrees. Degrees and radians are two ways of measuring the same thing. - * There are 360 degrees in a circle and 2 × π (about 6.28) - * radians in a circle. For example, 90° = π ÷ 2 (about 1.57) - * radians. This function doesn't take into account the current - * angleMode(). + * Converts an angle measured in radians to its value in degrees. + * + * Degrees and radians are both units for measuring angles. There are 360˚ in + * one full rotation. A full rotation is 2 × π (about 6.28) radians. + * + * The same angle can be expressed in with either unit. For example, 90° is a + * quarter of a full rotation. The same angle is 2 × π ÷ 4 + * (about 1.57) radians. * * @method degrees * @param {Number} radians radians value to convert to degrees. @@ -334,23 +493,34 @@ p5.prototype.tan = function(angle) { * @example *
* - * let rad = QUARTER_PI; - * let deg = degrees(rad); - * text(`${round(rad, 2)} rad = ${deg}˚`, 10, 50); + * function setup() { + * createCanvas(100, 100); * - * describe('The text "0.79 rad = 45˚".'); + * background(200); + * + * // Calculate the angle conversion. + * let rad = QUARTER_PI; + * let deg = degrees(rad); + * + * // Display the conversion. + * text(`${round(rad, 2)} rad = ${deg}˚`, 10, 50); + * + * describe('The text "0.79 rad = 45˚".'); + * } * *
*/ p5.prototype.degrees = angle => angle * constants.RAD_TO_DEG; /** - * Converts an angle measurement in degrees to its corresponding value in - * radians. Degrees and radians are two ways of measuring the same thing. - * There are 360 degrees in a circle and 2 × π (about 6.28) - * radians in a circle. For example, 90° = π ÷ 2 (about 1.57) - * radians. This function doesn't take into account the current - * angleMode(). + * Converts an angle measured in degrees to its value in radians. + * + * Degrees and radians are both units for measuring angles. There are 360˚ in + * one full rotation. A full rotation is 2 × π (about 6.28) radians. + * + * The same angle can be expressed in with either unit. For example, 90° is a + * quarter of a full rotation. The same angle is 2 × π ÷ 4 + * (about 1.57) radians. * * @method radians * @param {Number} degrees degree value to convert to radians. @@ -359,44 +529,210 @@ p5.prototype.degrees = angle => angle * constants.RAD_TO_DEG; * @example *
* - * let deg = 45; - * let rad = radians(deg); - * text(`${deg}˚ = ${round(rad, 3)} rad`, 10, 50); + * function setup() { + * createCanvas(100, 100); * - * describe('The text "45˚ = 0.785 rad".'); + * background(200); + * + * // Caclulate the angle conversion. + * let deg = 45; + * let rad = radians(deg); + * + * // Display the angle conversion. + * text(`${deg}˚ = ${round(rad, 3)} rad`, 10, 50); + * + * describe('The text "45˚ = 0.785 rad".'); + * } * *
*/ p5.prototype.radians = angle => angle * constants.DEG_TO_RAD; /** - * Changes the way trigonometric functions interpret angle values. By default, - * the mode is `RADIANS`. + * Changes the unit system used to measure angles. + * + * Degrees and radians are both units for measuring angles. There are 360˚ in + * one full rotation. A full rotation is 2 × π (about 6.28) radians. + * + * Functions such as rotate() and + * sin() expect angles measured radians by default. + * Calling `angleMode(DEGREES)` switches to degrees. Calling + * `angleMode(RADIANS)` switches back to radians. + * + * Calling `angleMode()` with no arguments returns current angle mode, which + * is either `RADIANS` or `DEGREES`. * - * Calling `angleMode()` with no arguments returns current angle mode. * @method angleMode * @param {Constant} mode either RADIANS or DEGREES. + * * @example *
* - * let r = 40; - * push(); - * rotate(PI / 6); - * line(0, 0, r, 0); - * text('0.524 rad', r, 0); - * pop(); - * - * angleMode(DEGREES); - * push(); - * rotate(60); - * line(0, 0, r, 0); - * text('60˚', r, 0); - * pop(); - * - * describe('Two diagonal lines radiating from the top left corner of a square. The lines are oriented 30 degrees from the edges of the square and 30 degrees apart from each other.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Rotate 1/8 turn. + * rotate(QUARTER_PI); + * + * // Draw a line. + * line(0, 0, 80, 0); + * + * describe('A diagonal line radiating from the top-left corner of a square.'); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Use degrees. + * angleMode(DEGREES); + * + * // Rotate 1/8 turn. + * rotate(45); + * + * // Draw a line. + * line(0, 0, 80, 0); + * + * describe('A diagonal line radiating from the top-left corner of a square.'); + * } * *
* + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(50); + * + * // Calculate the angle to rotate. + * let angle = TWO_PI / 7; + * + * // Move the origin to the center. + * translate(50, 50); + * + * // Style the flower. + * noStroke(); + * fill(255, 50); + * + * // Draw the flower. + * for (let i = 0; i < 7; i += 1) { + * ellipse(0, 0, 80, 20); + * rotate(angle); + * } + * + * describe('A translucent white flower on a dark background.'); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(50); + * + * // Use degrees. + * angleMode(DEGREES); + * + * // Calculate the angle to rotate. + * let angle = 360 / 7; + * + * // Move the origin to the center. + * translate(50, 50); + * + * // Style the flower. + * noStroke(); + * fill(255, 50); + * + * // Draw the flower. + * for (let i = 0; i < 7; i += 1) { + * ellipse(0, 0, 80, 20); + * rotate(angle); + * } + * + * describe('A translucent white flower on a dark background.'); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * describe('A white ball on a string oscillates left and right.'); + * } + * + * function draw() { + * background(200); + * + * // Calculate the coordinates. + * let x = 30 * cos(frameCount * 0.05) + 50; + * let y = 50; + * + * // Draw the oscillator. + * line(50, y, x, y); + * circle(x, y, 20); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * // Use degrees. + * angleMode(DEGREES); + * + * describe('A white ball on a string oscillates left and right.'); + * } + * + * function draw() { + * background(200); + * + * // Calculate the coordinates. + * let x = 30 * cos(frameCount * 2.86) + 50; + * let y = 50; + * + * // Draw the oscillator. + * line(50, y, x, y); + * circle(x, y, 20); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Draw the upper line. + * rotate(PI / 6); + * line(0, 0, 80, 0); + * + * // Use degrees. + * angleMode(DEGREES); + * + * // Draw the lower line. + * rotate(30); + * line(0, 0, 80, 0); + * + * describe('Two diagonal lines radiating from the top-left corner of a square. The lines are oriented 30 degrees from the edges of the square and 30 degrees apart from each other.'); + * } + * + *
*/ /** * @method angleMode