Merge remote-tracking branch 'upstream/dev-2.0' into matrix-docs

Author: holomorfo

src/color/p5.Color.js

@@ -44,18 +44,23 @@ class Color {
 
   static colorMap = {};
   static #colorjsMaxes = {};
+  static #grayscaleMap = {};
 
   // Used to add additional color modes to p5.js
   // Uses underlying library's definition
   static addColorMode(mode, definition){
     ColorSpace.register(definition);
     Color.colorMap[mode] = definition.id;
+
     // Get colorjs maxes
     Color.#colorjsMaxes[mode] = Object.values(definition.coords).reduce((acc, v) => {
         acc.push(v.refRange || v.range);
         return acc;
       }, []);
     Color.#colorjsMaxes[mode].push([0, 1]);
+
+    // Get grayscale mapping
+    Color.#grayscaleMap[mode] = definition.fromGray;
   }
 
   constructor(vals, colorMode, colorMaxes) {
@@ -99,15 +104,38 @@ class Color {
       let mappedVals;
 
       if(colorMaxes){
+        // NOTE: need to consider different number of arguments (eg. CMYK)
         if(vals.length === 4){
           mappedVals = Color.mapColorRange(vals, this.mode, colorMaxes);
         }else if(vals.length === 3){
           mappedVals = Color.mapColorRange([vals[0], vals[1], vals[2]], this.mode, colorMaxes);
           mappedVals.push(1);
         }else if(vals.length === 2){
-          mappedVals = Color.mapColorRange([vals[0], vals[0], vals[0], vals[1]], this.mode, colorMaxes);
+          // Grayscale with alpha
+          if(Color.#grayscaleMap[this.mode]){
+            mappedVals = Color.#grayscaleMap[this.mode](vals[0], colorMaxes);
+          }else{
+            mappedVals = Color.mapColorRange([vals[0], vals[0], vals[0]], this.mode, colorMaxes);
+          }
+          const alphaMaxes = Array.isArray(colorMaxes[colorMaxes.length-1]) ?
+            colorMaxes[colorMaxes.length-1] :
+            [0, colorMaxes[colorMaxes.length-1]];
+          mappedVals.push(
+            map(
+              vals[1],
+              alphaMaxes[0],
+              alphaMaxes[1],
+              0,
+              1
+            )
+          );
         }else if(vals.length === 1){
-          mappedVals = Color.mapColorRange([vals[0], vals[0], vals[0]], this.mode, colorMaxes);
+          // Grayscale only
+          if(Color.#grayscaleMap[this.mode]){
+            mappedVals = Color.#grayscaleMap[this.mode](vals[0], colorMaxes);
+          }else{
+            mappedVals = Color.mapColorRange([vals[0], vals[0], vals[0]], this.mode, colorMaxes);
+          }
           mappedVals.push(1);
         }else{
           throw new Error('Invalid color');
@@ -652,6 +680,78 @@ function color(p5, fn, lifecycles){
    */
   p5.Color = Color;
 
+  sRGB.fromGray = P3.fromGray = function(val, maxes){
+    // Use blue max
+    const p5Maxes = maxes.map((max) => {
+      if(!Array.isArray(max)){
+        return [0, max];
+      }else{
+        return max;
+      }
+    });
+
+    const v = map(val, p5Maxes[2][0], p5Maxes[2][1], 0, 1);
+    return [v, v, v];
+  };
+
+  HSBSpace.fromGray = HSLSpace.fromGray = function(val, maxes){
+    // Use brightness max
+    const p5Maxes = maxes.map((max) => {
+      if(!Array.isArray(max)){
+        return [0, max];
+      }else{
+        return max;
+      }
+    });
+
+    const v = map(val, p5Maxes[2][0], p5Maxes[2][1], 0, 100);
+    return [0, 0, v];
+  };
+
+  HWBSpace.fromGray = function(val, maxes){
+    // Use Whiteness and Blackness to create number line
+    const p5Maxes = maxes.map((max) => {
+      if(!Array.isArray(max)){
+        return [0, max];
+      }else{
+        return max;
+      }
+    });
+
+    const wbMax =
+      (Math.abs(p5Maxes[1][0] - p5Maxes[1][1])) / 2 +
+      (Math.abs(p5Maxes[2][0] - p5Maxes[2][1])) / 2;
+
+    const nVal = map(val, 0, wbMax, 0, 100);
+    let white, black;
+    if(nVal < 50){
+      black = nVal;
+      white = 100 - nVal;
+    }else if(nVal >= 50){
+      white = nVal;
+      black = 100 - nVal;
+    }
+    return [0, white, black];
+  };
+
+  Lab.fromGray =
+  LCHSpace.fromGray =
+  OKLab.fromGray =
+  OKLCHSpace.fromGray =
+  function(val, maxes){
+    // Use lightness max
+    const p5Maxes = maxes.map((max) => {
+      if(!Array.isArray(max)){
+        return [0, max];
+      }else{
+        return max;
+      }
+    });
+
+    const v = map(val, p5Maxes[0][0], p5Maxes[0][1], 0, 100);
+    return [v, 0, 0];
+  };
+
   // Register color modes and initialize Color maxes to what p5 has set for itself
   p5.Color.addColorMode(RGB, sRGB);
   p5.Color.addColorMode(RGBHDR, P3);

src/image/loading_displaying.js

@@ -66,9 +66,9 @@ function loadingDisplaying(p5, fn){
    *
    * <div>
    * <code>
-   * function setup() {
+   * async function setup() {
    *   // Call handleImage() once the image loads.
-   *   loadImage('assets/laDefense.jpg', handleImage);
+   *   await loadImage('assets/laDefense.jpg', handleImage);
    *
    *   describe('Image of the underside of a white umbrella and a gridded ceiling.');
    * }
@@ -82,10 +82,10 @@ function loadingDisplaying(p5, fn){
    *
    * <div>
    * <code>
-   * function setup() {
+   * async function setup() {
    *   // Call handleImage() once the image loads or
    *   // call handleError() if an error occurs.
-   *   loadImage('assets/laDefense.jpg', handleImage, handleError);
+   *   await loadImage('assets/laDefense.jpg', handleImage, handleError);
    * }
    *
    * // Display the image.
@@ -995,7 +995,7 @@ function loadingDisplaying(p5, fn){
    *
    * async function setup() {
    *   // Load the image.
-   *   img = await loadImage('assets/laDefense50.jpg');
+   *   img = await loadImage('assets/laDefense50.png');
    *
    *   createCanvas(100, 100);
    *

src/shape/curves.js

@@ -505,7 +505,7 @@ function curves(p5, fn){
    *   noFill();
    *   strokeWeight(1);
    *   stroke(0);
-   *   curve(5, 26, 73, 24, 73, 61, 15, 65);
+   *   spline(5, 26, 73, 24, 73, 61, 15, 65);
    *
    *   // Draw red spline curves from the anchor points to the control points.
    *   stroke(255, 0, 0);
@@ -653,8 +653,6 @@ function curves(p5, fn){
    * @chainable
    */
   fn.spline = function(...args) {
-    // p5._validateParameters('curve', args);
-
     if (!this._renderer.states.strokeColor && !this._renderer.states.fillColor) {
       return this;
     }
@@ -666,9 +664,9 @@ function curves(p5, fn){
   /**
    * Calculates coordinates along a spline curve using interpolation.
    *
-   * `curvePoint()` calculates coordinates along a spline curve using the
+   * `splinePoint()` calculates coordinates along a spline curve using the
    * anchor and control points. It expects points in the same order as the
-   * <a href="#/p5/curve">curve()</a> function. `curvePoint()` works one axis
+   * <a href="#/p5/spline">spline()</a> function. `splinePoint()` works one axis
    * at a time. Passing the anchor and control points' x-coordinates will
    * calculate the x-coordinate of a point on the curve. Passing the anchor and
    * control points' y-coordinates will calculate the y-coordinate of a point on
@@ -685,7 +683,7 @@ function curves(p5, fn){
    * is the first anchor point, 1 is the second anchor point, and 0.5 is halfway
    * between them.
    *
-   * @method curvePoint
+   * @method splinePoint
    * @param {Number} a coordinate of first anchor point.
    * @param {Number} b coordinate of first control point.
    * @param {Number} c coordinate of second control point.
@@ -713,24 +711,24 @@ function curves(p5, fn){
    *
    *   // Draw the curve.
    *   noFill();
-   *   curve(x1, y1, x2, y2, x3, y3, x4, y4);
+   *   spline(x1, y1, x2, y2, x3, y3, x4, y4);
    *
    *   // Draw circles along the curve's path.
    *   fill(255);
    *
    *   // Top.
-   *   let x = curvePoint(x1, x2, x3, x4, 0);
-   *   let y = curvePoint(y1, y2, y3, y4, 0);
+   *   let x = splinePoint(x1, x2, x3, x4, 0);
+   *   let y = splinePoint(y1, y2, y3, y4, 0);
    *   circle(x, y, 5);
    *
    *   // Center.
-   *   x = curvePoint(x1, x2, x3, x4, 0.5);
-   *   y = curvePoint(y1, y2, y3, y4, 0.5);
+   *   x = splinePoint(x1, x2, x3, x4, 0.5);
+   *   y = splinePoint(y1, y2, y3, y4, 0.5);
    *   circle(x, y, 5);
    *
    *   // Bottom.
-   *   x = curvePoint(x1, x2, x3, x4, 1);
-   *   y = curvePoint(y1, y2, y3, y4, 1);
+   *   x = splinePoint(x1, x2, x3, x4, 1);
+   *   y = splinePoint(y1, y2, y3, y4, 1);
    *   circle(x, y, 5);
    *
    *   describe('A black curve on a gray square. The endpoints and center of the curve are marked with white circles.');
@@ -761,12 +759,12 @@ function curves(p5, fn){
    *
    *   // Draw the curve.
    *   noFill();
-   *   curve(x1, y1, x2, y2, x3, y3, x4, y4);
+   *   spline(x1, y1, x2, y2, x3, y3, x4, y4);
    *
    *   // Calculate the circle's coordinates.
    *   let t = 0.5 * sin(frameCount * 0.01) + 0.5;
-   *   let x = curvePoint(x1, x2, x3, x4, t);
-   *   let y = curvePoint(y1, y2, y3, y4, t);
+   *   let x = splinePoint(x1, x2, x3, x4, t);
+   *   let y = splinePoint(y1, y2, y3, y4, t);
    *
    *   // Draw the circle.
    *   fill(255);
@@ -775,8 +773,7 @@ function curves(p5, fn){
    * </code>
    * </div>
    */
-  fn.curvePoint = function(a, b, c, d, t) {
-    // p5._validateParameters('curvePoint', arguments);
+  fn.splinePoint = function(a, b, c, d, t) {
     const s = this._renderer.states.splineProperties.tightness,
       t3 = t * t * t,
       t2 = t * t,
@@ -793,9 +790,9 @@ function curves(p5, fn){
    * Tangent lines skim the surface of a curve. A tangent line's slope equals
    * the curve's slope at the point where it intersects.
    *
-   * `curveTangent()` calculates coordinates along a tangent line using the
+   * `splineTangent()` calculates coordinates along a tangent line using the
    * spline curve's anchor and control points. It expects points in the same
-   * order as the <a href="#/p5/curve">curve()</a> function. `curveTangent()`
+   * order as the <a href="#/p5/spline">spline()</a> function. `splineTangent()`
    * works one axis at a time. Passing the anchor and control points'
    * x-coordinates will calculate the x-coordinate of a point on the tangent
    * line. Passing the anchor and control points' y-coordinates will calculate
@@ -812,7 +809,7 @@ function curves(p5, fn){
    * is the first anchor point, 1 is the second anchor point, and 0.5 is halfway
    * between them.
    *
-   * @method curveTangent
+   * @method splineTangent
    * @param {Number} a coordinate of first control point.
    * @param {Number} b coordinate of first anchor point.
    * @param {Number} c coordinate of second anchor point.
@@ -840,48 +837,48 @@ function curves(p5, fn){
    *
    *   // Draw the curve.
    *   noFill();
-   *   curve(x1, y1, x2, y2, x3, y3, x4, y4);
+   *   spline(x1, y1, x2, y2, x3, y3, x4, y4);
    *
    *   // Draw tangents along the curve's path.
    *   fill(255);
    *
    *   // Top circle.
    *   stroke(0);
-   *   let x = curvePoint(x1, x2, x3, x4, 0);
-   *   let y = curvePoint(y1, y2, y3, y4, 0);
+   *   let x = splinePoint(x1, x2, x3, x4, 0);
+   *   let y = splinePoint(y1, y2, y3, y4, 0);
    *   circle(x, y, 5);
    *
    *   // Top tangent line.
    *   // Scale the tangent point to draw a shorter line.
    *   stroke(255, 0, 0);
-   *   let tx = 0.2 * curveTangent(x1, x2, x3, x4, 0);
-   *   let ty = 0.2 * curveTangent(y1, y2, y3, y4, 0);
+   *   let tx = 0.2 * splineTangent(x1, x2, x3, x4, 0);
+   *   let ty = 0.2 * splineTangent(y1, y2, y3, y4, 0);
    *   line(x + tx, y + ty, x - tx, y - ty);
    *
    *   // Center circle.
    *   stroke(0);
-   *   x = curvePoint(x1, x2, x3, x4, 0.5);
-   *   y = curvePoint(y1, y2, y3, y4, 0.5);
+   *   x = splinePoint(x1, x2, x3, x4, 0.5);
+   *   y = splinePoint(y1, y2, y3, y4, 0.5);
    *   circle(x, y, 5);
    *
    *   // Center tangent line.
    *   // Scale the tangent point to draw a shorter line.
    *   stroke(255, 0, 0);
-   *   tx = 0.2 * curveTangent(x1, x2, x3, x4, 0.5);
-   *   ty = 0.2 * curveTangent(y1, y2, y3, y4, 0.5);
+   *   tx = 0.2 * splineTangent(x1, x2, x3, x4, 0.5);
+   *   ty = 0.2 * splineTangent(y1, y2, y3, y4, 0.5);
    *   line(x + tx, y + ty, x - tx, y - ty);
    *
    *   // Bottom circle.
    *   stroke(0);
-   *   x = curvePoint(x1, x2, x3, x4, 1);
-   *   y = curvePoint(y1, y2, y3, y4, 1);
+   *   x = splinePoint(x1, x2, x3, x4, 1);
+   *   y = splinePoint(y1, y2, y3, y4, 1);
    *   circle(x, y, 5);
    *
    *   // Bottom tangent line.
    *   // Scale the tangent point to draw a shorter line.
    *   stroke(255, 0, 0);
-   *   tx = 0.2 * curveTangent(x1, x2, x3, x4, 1);
-   *   ty = 0.2 * curveTangent(y1, y2, y3, y4, 1);
+   *   tx = 0.2 * splineTangent(x1, x2, x3, x4, 1);
+   *   ty = 0.2 * splineTangent(y1, y2, y3, y4, 1);
    *   line(x + tx, y + ty, x - tx, y - ty);
    *
    *   describe(
@@ -891,9 +888,7 @@ function curves(p5, fn){
    * </code>
    * </div>
    */
-  fn.curveTangent = function(a, b, c, d, t) {
-    // p5._validateParameters('curveTangent', arguments);
-
+  fn.splineTangent = function(a, b, c, d, t) {
     const s = this._renderer.states.splineProperties.tightness,
       tt3 = t * t * 3,
       t2 = t * 2,