fabric 5.3.0 → 6.0.0-beta3

package/src/util/misc/projectStroke/StrokeLineJoinProjections.ts

@@ -0,0 +1,226 @@
+import { XY, Point } from '../../../Point';
+import { degreesToRadians } from '../radiansDegreesConversion';
+import { getBisector, getOrthonormalVector, magnitude } from '../vectors';
+import { StrokeProjectionsBase } from './StrokeProjectionsBase';
+import { TProjection, TProjectStrokeOnPointsOptions } from './types';
+
+/**
+ * class in charge of finding projections for each type of line join
+ * @see {@link [Closed path projections at #8344](https://github.com/fabricjs/fabric.js/pull/8344#2-closed-path)}
+ *
+ * - MDN:
+ *   - https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
+ *   - https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linejoin
+ * - Spec: https://svgwg.org/svg2-draft/painting.html#StrokeLinejoinProperty
+ * - Playground to understand how the line joins works: https://hypertolosana.github.io/efficient-webgl-stroking/index.html
+ * - View the calculated projections for each of the control points: https://codesandbox.io/s/project-stroke-points-with-context-to-trace-b8jc4j?file=/src/index.js
+ *
+ */
+export class StrokeLineJoinProjections extends StrokeProjectionsBase {
+  /**
+   * The point being projected (the angle ∠BAC)
+   */
+  declare A: Point;
+  /**
+   * The point before A
+   */
+  declare B: Point;
+  /**
+   * The point after A
+   */
+  declare C: Point;
+  /**
+   * The bisector of A (∠BAC)
+   */
+  declare bisector: ReturnType<typeof getBisector>;
+
+  constructor(A: XY, B: XY, C: XY, options: TProjectStrokeOnPointsOptions) {
+    super(options);
+    this.A = new Point(A);
+    this.B = new Point(B);
+    this.C = new Point(C);
+    // First we calculate the bisector between the points. Used in `round` and `miter` cases
+    // When the stroke is uniform, scaling changes the arrangement of the points, so we have to take it into account
+    this.bisector = this.options.strokeUniform
+      ? getBisector(
+          this.A.multiply(this.scale),
+          this.B.multiply(this.scale),
+          this.C.multiply(this.scale)
+        )
+      : getBisector(this.A, this.B, this.C);
+  }
+
+  get bisectorVector() {
+    return this.bisector.vector;
+  }
+
+  get bisectorAngle() {
+    return this.bisector.angle;
+  }
+
+  calcOrthogonalProjection(
+    from: Point,
+    to: Point,
+    magnitude: number = this.strokeProjectionMagnitude
+  ) {
+    const vector = this.createSideVector(from, to);
+    const orthogonalProjection = getOrthonormalVector(vector);
+    const correctSide = StrokeProjectionsBase.getAcuteAngleFactor(
+      orthogonalProjection,
+      this.bisectorVector
+    );
+    return this.scaleUnitVector(orthogonalProjection, magnitude * correctSide);
+  }
+
+  /**
+   * BEVEL
+   * Calculation: the projection points are formed by the vector orthogonal to the vertex.
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#2-2-bevel
+   */
+  projectBevel() {
+    return [this.B, this.C].map((to) => this.projectOrthogonally(this.A, to));
+  }
+
+  /**
+   * MITER
+   * Calculation: the corner is formed by extending the outer edges of the stroke
+   * at the tangents of the path segments until they intersect.
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#2-1-miter
+   */
+  projectMiter() {
+    const alpha = Math.abs(this.bisectorAngle),
+      hypotUnitScalar = 1 / Math.sin(alpha / 2),
+      miterVector = this.scaleUnitVector(
+        this.bisectorVector,
+        -this.strokeProjectionMagnitude * hypotUnitScalar
+      );
+
+    // When two line segments meet at a sharp angle, it is possible for the join to extend,
+    // far beyond the thickness of the line stroking the path. The stroke-miterlimit imposes
+    // a limit on the extent of the line join.
+    // MDN: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-miterlimit
+    // When the stroke is uniform, scaling changes the arrangement of points, this changes the miter-limit
+    const strokeMiterLimit = this.options.strokeUniform
+      ? hypotUnitScalar
+      : this.options.strokeMiterLimit;
+
+    if (
+      magnitude(miterVector) / this.strokeProjectionMagnitude <=
+      strokeMiterLimit
+    ) {
+      return [this.applySkew(this.A.add(miterVector))];
+    } else {
+      // when the miter-limit is reached, the stroke line join becomes of type bevel
+      return this.projectBevel();
+    }
+  }
+
+  /**
+   * ROUND (without skew)
+   * Calculation: the projections are the two vectors parallel to X and Y axes
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#2-3-1-round-without-skew
+   */
+  private projectRoundNoSkew() {
+    // correctSide is used to only consider projecting for the outer side
+    const correctSide = new Point(
+        StrokeProjectionsBase.getAcuteAngleFactor(this.bisectorVector),
+        StrokeProjectionsBase.getAcuteAngleFactor(
+          new Point(this.bisectorVector.y, this.bisectorVector.x)
+        )
+      ),
+      radiusOnAxisX = new Point(1, 0)
+        .scalarMultiply(this.strokeProjectionMagnitude)
+        .multiply(this.strokeUniformScalar)
+        .multiply(correctSide),
+      radiusOnAxisY = new Point(0, 1)
+        .scalarMultiply(this.strokeProjectionMagnitude)
+        .multiply(this.strokeUniformScalar)
+        .multiply(correctSide);
+
+    return [this.A.add(radiusOnAxisX), this.A.add(radiusOnAxisY)];
+  }
+
+  /**
+   * ROUND (with skew)
+   * Calculation: the projections are the points furthest from the vertex in
+   * the direction of the X and Y axes after distortion.
+   *
+   * @todo TODO:
+   *  - Consider only projections that are inside the beginning and end of the circle segment
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#2-3-2-round-skew
+   */
+  private projectRoundWithSkew() {
+    const projections: Point[] = [];
+
+    // The start and end points of the circle segment
+    [this.B, this.C].forEach((to) =>
+      projections.push(this.projectOrthogonally(this.A, to))
+    );
+
+    const { skewX, skewY } = this.options;
+    // The points furthest from the vertex in the direction of the X and Y axes after distortion
+    const circleRadius = new Point()
+        .scalarAdd(this.strokeProjectionMagnitude)
+        .multiply(this.strokeUniformScalar),
+      newY =
+        circleRadius.y / Math.sqrt(1 + Math.tan(degreesToRadians(skewY)) ** 2),
+      furthestY = new Point(
+        Math.sqrt(
+          circleRadius.x ** 2 - ((newY * circleRadius.x) / circleRadius.y) ** 2
+        ),
+        newY
+      ),
+      newX =
+        circleRadius.x / Math.sqrt(1 + Math.tan(degreesToRadians(skewX)) ** 2),
+      furthestX = new Point(
+        newX,
+        Math.sqrt(newY ** 2 - ((newX * newY) / circleRadius.x) ** 2)
+      );
+
+    [furthestX, furthestY].forEach((vector) => {
+      projections.push(
+        this.applySkew(this.A.add(vector)),
+        this.applySkew(this.A.subtract(vector))
+      );
+    });
+
+    return projections;
+  }
+
+  projectRound() {
+    if (!this.isSkewed()) {
+      return this.projectRoundNoSkew();
+    } else {
+      return this.projectRoundWithSkew();
+    }
+  }
+
+  /**
+   * Project stroke width on points returning projections for each point as follows:
+   * - `miter`: 1 point corresponding to the outer boundary. If the miter limit is exceeded, it will be 2 points (becomes bevel)
+   * - `bevel`: 2 points corresponding to the bevel possible boundaries, orthogonal to the stroke.
+   * - `round`: same as `bevel` when it has no skew, with skew are 4 points.
+   */
+  protected projectPoints() {
+    switch (this.options.strokeLineJoin) {
+      case 'miter':
+        return this.projectMiter();
+      case 'round':
+        return this.projectRound();
+      default:
+        return this.projectBevel();
+    }
+  }
+
+  public project(): TProjection[] {
+    return this.projectPoints().map((point) => ({
+      originPoint: this.A,
+      projectedPoint: point,
+      bisector: this.bisector,
+    }));
+  }
+}

package/src/util/misc/projectStroke/StrokeProjectionsBase.ts

@@ -0,0 +1,75 @@
+import { halfPI } from '../../../constants';
+import { XY, Point } from '../../../Point';
+import { degreesToRadians } from '../radiansDegreesConversion';
+import {
+  calcAngleBetweenVectors,
+  calcVectorRotation,
+  createVector,
+} from '../vectors';
+import { TProjectStrokeOnPointsOptions, TProjection } from './types';
+
+/**
+ * @see https://github.com/fabricjs/fabric.js/pull/8344
+ */
+export abstract class StrokeProjectionsBase {
+  declare options: TProjectStrokeOnPointsOptions;
+  declare scale: Point;
+  declare strokeUniformScalar: Point;
+  declare strokeProjectionMagnitude: number;
+
+  static getAcuteAngleFactor(vector1: Point, vector2?: Point) {
+    const angle = vector2
+      ? calcAngleBetweenVectors(vector1, vector2)
+      : calcVectorRotation(vector1);
+    return Math.abs(angle) < halfPI ? -1 : 1;
+  }
+
+  constructor(options: TProjectStrokeOnPointsOptions) {
+    this.options = options;
+    this.strokeProjectionMagnitude = this.options.strokeWidth / 2;
+    this.scale = new Point(this.options.scaleX, this.options.scaleY);
+    this.strokeUniformScalar = this.options.strokeUniform
+      ? new Point(1 / this.options.scaleX, 1 / this.options.scaleY)
+      : new Point(1, 1);
+  }
+
+  /**
+   * When the stroke is uniform, scaling affects the arrangement of points. So we must take it into account.
+   */
+  protected createSideVector(from: XY, to: XY) {
+    const v = createVector(from, to);
+    return this.options.strokeUniform ? v.multiply(this.scale) : v;
+  }
+
+  protected abstract calcOrthogonalProjection(
+    from: Point,
+    to: Point,
+    magnitude?: number
+  ): Point;
+
+  protected projectOrthogonally(from: Point, to: Point, magnitude?: number) {
+    return this.applySkew(
+      from.add(this.calcOrthogonalProjection(from, to, magnitude))
+    );
+  }
+
+  protected isSkewed() {
+    return this.options.skewX !== 0 || this.options.skewY !== 0;
+  }
+
+  protected applySkew(point: Point) {
+    const p = new Point(point);
+    // skewY must be applied before skewX as this distortion affects skewX calculation
+    p.y += p.x * Math.tan(degreesToRadians(this.options.skewY));
+    p.x += p.y * Math.tan(degreesToRadians(this.options.skewX));
+    return p;
+  }
+
+  protected scaleUnitVector(unitVector: Point, scalar: number) {
+    return unitVector.multiply(this.strokeUniformScalar).scalarMultiply(scalar);
+  }
+
+  protected abstract projectPoints(): Point[];
+
+  public abstract project(): TProjection[];
+}

package/src/util/misc/projectStroke/index.ts

@@ -0,0 +1,53 @@
+import { XY } from '../../../Point';
+import { StrokeLineCapProjections } from './StrokeLineCapProjections';
+import { StrokeLineJoinProjections } from './StrokeLineJoinProjections';
+import { TProjection, TProjectStrokeOnPointsOptions } from './types';
+
+/**
+ *
+ * Used to calculate object's bounding box
+ *
+ * @see https://github.com/fabricjs/fabric.js/pull/8344
+ *
+ */
+export const projectStrokeOnPoints = (
+  points: XY[],
+  options: TProjectStrokeOnPointsOptions,
+  openPath = false
+): TProjection[] => {
+  const projections: TProjection[] = [];
+
+  if (points.length <= 1) {
+    return projections;
+  }
+
+  points.forEach((A, index) => {
+    let B: XY, C: XY;
+    if (index === 0) {
+      C = points[1];
+      B = openPath ? A : points[points.length - 1];
+    } else if (index === points.length - 1) {
+      B = points[index - 1];
+      C = openPath ? A : points[0];
+    } else {
+      B = points[index - 1];
+      C = points[index + 1];
+    }
+
+    if (openPath && (index === 0 || index === points.length - 1)) {
+      projections.push(
+        ...new StrokeLineCapProjections(
+          A,
+          index === 0 ? C : B,
+          options
+        ).project()
+      );
+    } else {
+      projections.push(
+        ...new StrokeLineJoinProjections(A, B, C, options).project()
+      );
+    }
+  });
+
+  return projections;
+};

package/src/util/misc/projectStroke/types.ts

@@ -0,0 +1,24 @@
+import { Point } from '../../../Point';
+import { TDegree } from '../../../typedefs';
+import { getBisector } from '../vectors';
+
+export type TProjectStrokeOnPointsOptions = {
+  strokeWidth: number;
+  strokeLineCap: CanvasLineCap;
+  strokeLineJoin: CanvasLineJoin;
+  /**
+   * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-miterlimit
+   */
+  strokeMiterLimit: number;
+  strokeUniform: boolean;
+  scaleX: number;
+  scaleY: number;
+  skewX: TDegree;
+  skewY: TDegree;
+};
+
+export type TProjection = {
+  projectedPoint: Point;
+  originPoint: Point;
+  bisector?: ReturnType<typeof getBisector>;
+};

package/src/util/misc/radiansDegreesConversion.ts

@@ -0,0 +1,18 @@
+import type { TRadian, TDegree } from '../../typedefs';
+import { PiBy180 } from '../../constants';
+
+/**
+ * Transforms degrees to radians.
+ * @param {TDegree} degrees value in degrees
+ * @return {TRadian} value in radians
+ */
+export const degreesToRadians = (degrees: TDegree): TRadian =>
+  (degrees * PiBy180) as TRadian;
+
+/**
+ * Transforms radians to degrees.
+ * @param {TRadian} radians value in radians
+ * @return {TDegree} value in degrees
+ */
+export const radiansToDegrees = (radians: TRadian): TDegree =>
+  (radians / PiBy180) as TDegree;

package/src/util/misc/resolveOrigin.ts

@@ -0,0 +1,22 @@
+import { TOriginX, TOriginY } from '../../typedefs';
+
+const originOffset = {
+  left: -0.5,
+  top: -0.5,
+  center: 0,
+  bottom: 0.5,
+  right: 0.5,
+};
+/**
+ * Resolves origin value relative to center
+ * @private
+ * @param {TOriginX | TOriginY} originValue originX / originY
+ * @returns number
+ */
+
+export const resolveOrigin = (
+  originValue: TOriginX | TOriginY | number
+): number =>
+  typeof originValue === 'string'
+    ? originOffset[originValue]
+    : originValue - 0.5;

package/src/util/misc/rotatePoint.ts

@@ -0,0 +1,15 @@
+import type { Point } from '../../Point';
+import type { TRadian } from '../../typedefs';
+/**
+ * Rotates `point` around `origin` with `radians`
+ * @deprecated use the Point.rotate
+ * @param {Point} origin The origin of the rotation
+ * @param {Point} origin The origin of the rotation
+ * @param {TRadian} radians The radians of the angle for the rotation
+ * @return {Point} The new rotated point
+ */
+export const rotatePoint = (
+  point: Point,
+  origin: Point,
+  radians: TRadian
+): Point => point.rotate(radians, origin);

package/src/util/misc/sin.ts

@@ -0,0 +1,26 @@
+import type { TRadian } from '../../typedefs';
+import { halfPI } from '../../constants';
+
+/**
+ * Calculate the cos of an angle, avoiding returning floats for known results
+ * This function is here just to avoid getting 0.999999999999999 when dealing
+ * with numbers that are really 1 or 0.
+ * @param {TRadian} angle the angle
+ * @return {Number} the sin value for angle.
+ */
+export const sin = (angle: TRadian): number => {
+  if (angle === 0) {
+    return 0;
+  }
+  const angleSlice = angle / halfPI;
+  const value = Math.sign(angle);
+  switch (angleSlice) {
+    case 1:
+      return value;
+    case 2:
+      return 0;
+    case 3:
+      return -value;
+  }
+  return Math.sin(angle);
+};

package/src/util/misc/svgParsing.ts

@@ -0,0 +1,181 @@
+import { Color } from '../../color/Color';
+import { config } from '../../config';
+import { DEFAULT_SVG_FONT_SIZE } from '../../constants';
+import {
+  SupportedSVGUnit,
+  SVGElementName,
+  TBBox,
+  TMat2D,
+} from '../../typedefs';
+import { toFixed } from './toFixed';
+/**
+ * Returns array of attributes for given svg that fabric parses
+ * @param {SVGElementName} type Type of svg element (eg. 'circle')
+ * @return {Array} string names of supported attributes
+ */
+export const getSvgAttributes = (type: SVGElementName) => {
+  const commonAttributes = ['instantiated_by_use', 'style', 'id', 'class'];
+  switch (type) {
+    case SVGElementName.linearGradient:
+      return commonAttributes.concat([
+        'x1',
+        'y1',
+        'x2',
+        'y2',
+        'gradientUnits',
+        'gradientTransform',
+      ]);
+    case 'radialGradient':
+      return commonAttributes.concat([
+        'gradientUnits',
+        'gradientTransform',
+        'cx',
+        'cy',
+        'r',
+        'fx',
+        'fy',
+        'fr',
+      ]);
+    case 'stop':
+      return commonAttributes.concat(['offset', 'stop-color', 'stop-opacity']);
+  }
+  return commonAttributes;
+};
+
+/**
+ * Converts from attribute value to pixel value if applicable.
+ * Returns converted pixels or original value not converted.
+ * @param {string} value number to operate on
+ * @param {number} fontSize
+ * @return {number}
+ */
+export const parseUnit = (value: string, fontSize: number) => {
+  const unit = /\D{0,2}$/.exec(value),
+    number = parseFloat(value);
+  if (!fontSize) {
+    fontSize = DEFAULT_SVG_FONT_SIZE;
+  }
+  const dpi = config.DPI;
+  switch (unit?.[0]) {
+    case SupportedSVGUnit.mm:
+      return (number * dpi) / 25.4;
+
+    case SupportedSVGUnit.cm:
+      return (number * dpi) / 2.54;
+
+    case SupportedSVGUnit.in:
+      return number * dpi;
+
+    case SupportedSVGUnit.pt:
+      return (number * dpi) / 72; // or * 4 / 3
+
+    case SupportedSVGUnit.pc:
+      return ((number * dpi) / 72) * 12; // or * 16
+
+    case SupportedSVGUnit.em:
+      return number * fontSize;
+
+    default:
+      return number;
+  }
+};
+
+export const enum MeetOrSlice {
+  meet = 'meet',
+  slice = 'slice',
+}
+
+export const enum MinMidMax {
+  min = 'Min',
+  mid = 'Mid',
+  max = 'Max',
+  none = 'none',
+}
+
+export type TPreserveArParsed = {
+  meetOrSlice: MeetOrSlice;
+  alignX: MinMidMax;
+  alignY: MinMidMax;
+};
+
+// align can be either none or undefined or a combination of mid/max
+const parseAlign = (align: string): MinMidMax[] => {
+  //divide align in alignX and alignY
+  if (align && align !== MinMidMax.none) {
+    return [align.slice(1, 4) as MinMidMax, align.slice(5, 8) as MinMidMax];
+  } else if (align === MinMidMax.none) {
+    return [align, align];
+  }
+  return [MinMidMax.mid, MinMidMax.mid];
+};
+
+/**
+ * Parse preserveAspectRatio attribute from element
+ * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio
+ * @param {string} attribute to be parsed
+ * @return {Object} an object containing align and meetOrSlice attribute
+ */
+export const parsePreserveAspectRatioAttribute = (
+  attribute: string
+): TPreserveArParsed => {
+  const [firstPart, secondPart] = attribute.trim().split(' ') as [
+    MinMidMax,
+    MeetOrSlice | undefined
+  ];
+  const [alignX, alignY] = parseAlign(firstPart);
+  return {
+    meetOrSlice: secondPart || MeetOrSlice.meet,
+    alignX,
+    alignY,
+  };
+};
+
+/**
+ * given an array of 6 number returns something like `"matrix(...numbers)"`
+ * @param {TMat2D} transform an array with 6 numbers
+ * @return {String} transform matrix for svg
+ */
+export const matrixToSVG = (transform: TMat2D) =>
+  'matrix(' +
+  transform
+    .map((value) => toFixed(value, config.NUM_FRACTION_DIGITS))
+    .join(' ') +
+  ')';
+
+/**
+ * Adobe Illustrator (at least CS5) is unable to render rgba()-based fill values
+ * we work around it by "moving" alpha channel into opacity attribute and setting fill's alpha to 1
+ * @param prop
+ * @param value
+ * @returns
+ */
+export const colorPropToSVG = (prop: string, value?: any) => {
+  if (!value) {
+    return `${prop}: none; `;
+  } else if (value.toLive) {
+    return `${prop}: url(#SVGID_${value.id}); `;
+  } else {
+    const color = new Color(value),
+      opacity = color.getAlpha();
+
+    let str = `${prop}: ${color.toRgb()}; `;
+
+    if (opacity !== 1) {
+      //change the color in rgb + opacity
+      str += `${prop}-opacity: ${opacity.toString()}; `;
+    }
+    return str;
+  }
+};
+
+export const createSVGRect = (
+  color: string,
+  { left, top, width, height }: TBBox,
+  precision = config.NUM_FRACTION_DIGITS
+) => {
+  const svgColor = colorPropToSVG('fill', color);
+  const [x, y, w, h] = [left, top, width, height].map((value) =>
+    toFixed(value, precision)
+  );
+  return `<rect ${svgColor} x="${x}" y="${y}" width="${w}" height="${h}"></rect>`;
+};