@canvas-commons/2d 0.2.0

package/src/lib/curves/getBezierSplineProfile.ts

@@ -0,0 +1,227 @@
+import {Vector2, clamp} from '@canvas-commons/core';
+import {CubicBezierSegment} from './CubicBezierSegment';
+import {CurveProfile} from './CurveProfile';
+import {KnotInfo} from './KnotInfo';
+import {PolynomialSegment} from './PolynomialSegment';
+import {QuadBezierSegment} from './QuadBezierSegment';
+
+function isCubicSegment(
+  segment: PolynomialSegment,
+): segment is CubicBezierSegment {
+  return segment instanceof CubicBezierSegment;
+}
+
+/**
+ * Update a given knot's handles to be a blend between the user provided handles
+ * and a set of auto calculated handles that smoothly connect the knot to its
+ * two neighboring knots.
+ *
+ * @param knot - The knot for which to calculate the handles
+ * @param previous - The previous knot in the spline, relative to the provided
+ *                   knot.
+ * @param next - The next knot in the spline, relative to the provided knot.
+ * @param smoothness - The desired smoothness of the spline. Affects the scaling
+ *                     of the auto calculated handles.
+ */
+function calculateSmoothHandles(
+  knot: KnotInfo,
+  previous: KnotInfo,
+  next: KnotInfo,
+  smoothness: number,
+) {
+  if (knot.auto.start === 0 && knot.auto.end === 0) {
+    return;
+  }
+
+  // See for reference:
+  // http://scaledinnovation.com/analytics/splines/aboutSplines.html
+  const distanceToPrev = knot.position.sub(previous.position).magnitude;
+  const distanceToNext = next.position.sub(knot.position).magnitude;
+  const fa = (smoothness * distanceToPrev) / (distanceToPrev + distanceToNext);
+  const fb = smoothness - fa;
+  const startHandle = new Vector2(
+    knot.position.x - fa * (next.position.x - previous.position.x),
+    knot.position.y - fa * (next.position.y - previous.position.y),
+  );
+  const endHandle = new Vector2(
+    knot.position.x + fb * (next.position.x - previous.position.x),
+    knot.position.y + fb * (next.position.y - previous.position.y),
+  );
+
+  knot.startHandle = knot.startHandle.lerp(startHandle, knot.auto.start);
+  knot.endHandle = knot.endHandle.lerp(endHandle, knot.auto.end);
+}
+
+/**
+ * Calculate the `minSin` value of the curve profile so that miter joins get
+ * taken into account properly.
+ */
+function updateMinSin(profile: CurveProfile) {
+  for (let i = 0; i < profile.segments.length; i++) {
+    const segmentA = profile.segments[i] as PolynomialSegment;
+    const segmentB = profile.segments[
+      (i + 1) % profile.segments.length
+    ] as PolynomialSegment;
+
+    // Quadratic Bézier segments will always join smoothly with the previous
+    // segment. This means that we can skip the segment since it's impossible
+    // to have a miter join between the two segments.
+    if (!isCubicSegment(segmentA) || !isCubicSegment(segmentB)) {
+      continue;
+    }
+
+    const startVector = segmentA.p2.sub(segmentA.p3).normalized.safe;
+    const endVector = segmentB.p1.sub(segmentB.p0).normalized.safe;
+    const dot = startVector.dot(endVector);
+
+    // A miter join can only occur if the handle is broken, so we can skip the
+    // segment if the handles are mirrored.
+    const isBroken = 1 - Math.abs(dot) > 0.0001;
+    if (!isBroken) {
+      continue;
+    }
+
+    const angleBetween = Math.acos(clamp(-1, 1, dot));
+    const angleSin = Math.sin(angleBetween / 2);
+
+    profile.minSin = Math.min(profile.minSin, Math.abs(angleSin));
+  }
+}
+
+function addSegmentToProfile(
+  profile: CurveProfile,
+  p0: Vector2,
+  p1: Vector2,
+  p2: Vector2,
+  p3?: Vector2,
+) {
+  const segment =
+    p3 !== undefined
+      ? new CubicBezierSegment(p0, p1, p2, p3)
+      : new QuadBezierSegment(p0, p1, p2);
+  profile.segments.push(segment);
+  profile.arcLength += segment.arcLength;
+}
+
+/**
+ * Calculate the curve profile of a spline based on a set of knots.
+ *
+ * @param knots - The knots defining the spline
+ * @param closed - Whether the spline should be closed or not
+ * @param smoothness - The desired smoothness of the spline when using auto
+ *                     calculated handles.
+ */
+export function getBezierSplineProfile(
+  knots: KnotInfo[],
+  closed: boolean,
+  smoothness: number,
+): CurveProfile {
+  const profile: CurveProfile = {
+    segments: [],
+    arcLength: 0,
+    minSin: 1,
+  };
+
+  if (knots.length < 2) {
+    return profile;
+  }
+
+  // First, we want to calculate the actual handle positions for each knot. We
+  // do so using the knot's `auto` value to blend between the user-provided
+  // handles and the auto calculated smooth handles.
+  const numberOfKnots = knots.length;
+  for (let i = 0; i < numberOfKnots; i++) {
+    // Calculating the auto handles for a given knot requires both of the knot's
+    // neighboring knots. To make sure that this works properly for the first
+    // and last knots of the spline, we want to make sure to wrap around to the
+    // beginning and end of the array, respectively.
+    const prevIndex = (i - 1 + numberOfKnots) % numberOfKnots;
+    const nextIndex = (i + 1) % numberOfKnots;
+    calculateSmoothHandles(
+      knots[i],
+      knots[prevIndex],
+      knots[nextIndex],
+      smoothness,
+    );
+  }
+
+  const firstKnot = knots[0];
+  const secondKnot = knots[1];
+
+  // Drawing the first and last segments of a spline has a few edge cases we
+  // need to consider:
+  // If the spline is not closed and the first knot should use the auto
+  // calculated handles, we want to draw a quadratic Bézier curve instead of a
+  // cubic one.
+  if (!closed && firstKnot.auto.start === 1 && firstKnot.auto.end === 1) {
+    addSegmentToProfile(
+      profile,
+      firstKnot.position,
+      secondKnot.startHandle,
+      secondKnot.position,
+    );
+  } else {
+    // Otherwise, draw a cubic Bézier segment like we do for the other segments.
+    addSegmentToProfile(
+      profile,
+      firstKnot.position,
+      firstKnot.endHandle,
+      secondKnot.startHandle,
+      secondKnot.position,
+    );
+  }
+
+  // Add all intermediate spline segments as cubic Bézier curve segments.
+  for (let i = 1; i < numberOfKnots - 2; i++) {
+    const start = knots[i];
+    const end = knots[i + 1];
+    addSegmentToProfile(
+      profile,
+      start.position,
+      start.endHandle,
+      end.startHandle,
+      end.position,
+    );
+  }
+
+  const lastKnot = knots.at(-1)!;
+  const secondToLastKnot = knots.at(-2)!;
+
+  if (knots.length > 2) {
+    // Similar to the first segment, we also want to draw the last segment as a
+    // quadratic Bézier curve if the curve is not closed and the knot should
+    // use the auto calculated handles.
+    if (!closed && lastKnot.auto.start === 1 && lastKnot.auto.end === 1) {
+      addSegmentToProfile(
+        profile,
+        secondToLastKnot.position,
+        secondToLastKnot.endHandle,
+        lastKnot.position,
+      );
+    } else {
+      addSegmentToProfile(
+        profile,
+        secondToLastKnot.position,
+        secondToLastKnot.endHandle,
+        lastKnot.startHandle,
+        lastKnot.position,
+      );
+    }
+  }
+
+  // If the spline should be closed, add one final cubic Bézier segment
+  // connecting the last and first knots.
+  if (closed) {
+    addSegmentToProfile(
+      profile,
+      lastKnot.position,
+      lastKnot.endHandle,
+      firstKnot.startHandle,
+      firstKnot.position,
+    );
+  }
+
+  updateMinSin(profile);
+
+  return profile;
+}

package/src/lib/curves/getCircleProfile.ts

@@ -0,0 +1,86 @@
+import {Vector2} from '@canvas-commons/core';
+import {ArcSegment} from './ArcSegment';
+import {CurveProfile} from './CurveProfile';
+import {LineSegment} from './LineSegment';
+import {Segment} from './Segment';
+
+export function getCircleProfile(
+  size: Vector2,
+  startAngle: number,
+  endAngle: number,
+  closed: boolean,
+  counterclockwise = false,
+): CurveProfile {
+  const profile: CurveProfile = {
+    arcLength: 0,
+    minSin: 1,
+    segments: [],
+  };
+
+  if (endAngle < startAngle) {
+    const loops = Math.floor((startAngle - endAngle) / (Math.PI * 2)) + 1;
+    endAngle += Math.PI * 2 * loops;
+  } else if (endAngle > startAngle + Math.PI * 2) {
+    const loops = Math.floor((endAngle - startAngle) / (Math.PI * 2));
+    endAngle -= Math.PI * 2 * loops;
+  }
+
+  const middleAngle = (startAngle + endAngle) / 2;
+  const from = size.mul(Vector2.fromRadians(startAngle));
+  const to = size.mul(Vector2.fromRadians(endAngle));
+  const middle = size
+    .mul(Vector2.fromRadians(middleAngle))
+    .scale(counterclockwise ? -1 : 1);
+
+  if (closed) {
+    addSegment(profile, new LineSegment(Vector2.zero, from));
+  }
+
+  addArcSegment(
+    profile,
+    size,
+    from,
+    middle,
+    startAngle,
+    middleAngle,
+    counterclockwise,
+  );
+  addArcSegment(
+    profile,
+    size,
+    middle,
+    to,
+    middleAngle,
+    endAngle,
+    counterclockwise,
+  );
+
+  if (closed) {
+    addSegment(profile, new LineSegment(to, Vector2.zero));
+  }
+
+  return profile;
+}
+
+function addSegment(profile: CurveProfile, segment: Segment) {
+  profile.segments.push(segment);
+  profile.arcLength += segment.arcLength;
+}
+
+function addArcSegment(
+  profile: CurveProfile,
+  size: Vector2,
+  from: Vector2,
+  to: Vector2,
+  fromAngle: number,
+  toAngle: number,
+  counterclockwise: boolean,
+) {
+  const small = Math.abs(fromAngle - toAngle) <= 180 ? 1 : 0;
+  const flip = fromAngle > toAngle ? 0 : 1;
+  const counter = counterclockwise ? 0 : 1;
+  addSegment(
+    profile,
+    new ArcSegment(from, size, 0, 0, small ^ counter ^ flip, to),
+  );
+}

package/src/lib/curves/getPathProfile.ts

@@ -0,0 +1,177 @@
+import {Vector2, clamp} from '@canvas-commons/core';
+import parse, {PathCommand} from 'parse-svg-path';
+import {ArcSegment} from './ArcSegment';
+import {CubicBezierSegment} from './CubicBezierSegment';
+import {CurveProfile} from './CurveProfile';
+import {LineSegment} from './LineSegment';
+import {QuadBezierSegment} from './QuadBezierSegment';
+import {Segment} from './Segment';
+
+function addSegmentToProfile(profile: CurveProfile, segment: Segment) {
+  profile.segments.push(segment);
+  profile.arcLength += segment.arcLength;
+}
+
+function getArg(command: PathCommand, argumentIndex: number) {
+  return command[argumentIndex + 1] as number;
+}
+
+function getVector2(command: PathCommand, argumentIndex: number) {
+  return new Vector2(
+    command[argumentIndex + 1] as number,
+    command[argumentIndex + 2] as number,
+  );
+}
+
+function getPoint(
+  command: PathCommand,
+  argumentIndex: number,
+  isRelative: boolean,
+  currentPoint: Vector2,
+) {
+  const point = getVector2(command, argumentIndex);
+  return isRelative ? currentPoint.add(point) : point;
+}
+
+function reflectControlPoint(control: Vector2, currentPoint: Vector2) {
+  return currentPoint.add(currentPoint.sub(control));
+}
+
+function updateMinSin(profile: CurveProfile) {
+  for (let i = 0; i < profile.segments.length; i++) {
+    const segmentA = profile.segments[i];
+    const segmentB = profile.segments[(i + 1) % profile.segments.length];
+
+    // In cubic bezier this equal p2.sub(p3)
+    const startVector = segmentA.getPoint(1).tangent.scale(-1);
+    // In cubic bezier this equal p1.sub(p0)
+    const endVector = segmentB.getPoint(0).tangent;
+    const dot = startVector.dot(endVector);
+
+    const angleBetween = Math.acos(clamp(-1, 1, dot));
+    const angleSin = Math.sin(angleBetween / 2);
+
+    profile.minSin = Math.min(profile.minSin, Math.abs(angleSin));
+  }
+}
+
+export function getPathProfile(data: string): CurveProfile {
+  const profile: CurveProfile = {
+    segments: [],
+    arcLength: 0,
+    minSin: 1,
+  };
+
+  const segments = parse(data);
+  let currentPoint = new Vector2(0, 0);
+  let firstPoint: Vector2 | null = null;
+
+  for (const segment of segments) {
+    const command = segment[0].toLowerCase();
+    const isRelative = segment[0] === command;
+
+    if (command === 'm') {
+      currentPoint = getPoint(segment, 0, isRelative, currentPoint);
+      firstPoint = currentPoint;
+    } else if (command === 'l') {
+      const nextPoint = getPoint(segment, 0, isRelative, currentPoint);
+      addSegmentToProfile(profile, new LineSegment(currentPoint, nextPoint));
+      currentPoint = nextPoint;
+    } else if (command === 'h') {
+      const x = getArg(segment, 0);
+      const nextPoint = isRelative
+        ? currentPoint.addX(x)
+        : new Vector2(x, currentPoint.y);
+      addSegmentToProfile(profile, new LineSegment(currentPoint, nextPoint));
+      currentPoint = nextPoint;
+    } else if (command === 'v') {
+      const y = getArg(segment, 0);
+      const nextPoint = isRelative
+        ? currentPoint.addY(y)
+        : new Vector2(currentPoint.x, y);
+      addSegmentToProfile(profile, new LineSegment(currentPoint, nextPoint));
+      currentPoint = nextPoint;
+    } else if (command === 'q') {
+      const controlPoint = getPoint(segment, 0, isRelative, currentPoint);
+      const nextPoint = getPoint(segment, 2, isRelative, currentPoint);
+      addSegmentToProfile(
+        profile,
+        new QuadBezierSegment(currentPoint, controlPoint, nextPoint),
+      );
+      currentPoint = nextPoint;
+    } else if (command === 't') {
+      const lastSegment = profile.segments.at(-1);
+      const controlPoint =
+        lastSegment instanceof QuadBezierSegment
+          ? reflectControlPoint(lastSegment.p1, currentPoint)
+          : currentPoint;
+
+      const nextPoint = getPoint(segment, 0, isRelative, currentPoint);
+      addSegmentToProfile(
+        profile,
+        new QuadBezierSegment(currentPoint, controlPoint, nextPoint),
+      );
+      currentPoint = nextPoint;
+    } else if (command === 'c') {
+      const startControlPoint = getPoint(segment, 0, isRelative, currentPoint);
+      const endControlPoint = getPoint(segment, 2, isRelative, currentPoint);
+      const nextPoint = getPoint(segment, 4, isRelative, currentPoint);
+      addSegmentToProfile(
+        profile,
+        new CubicBezierSegment(
+          currentPoint,
+          startControlPoint,
+          endControlPoint,
+          nextPoint,
+        ),
+      );
+      currentPoint = nextPoint;
+    } else if (command === 's') {
+      const lastSegment = profile.segments.at(-1);
+      const startControlPoint =
+        lastSegment instanceof CubicBezierSegment
+          ? reflectControlPoint(lastSegment.p2, currentPoint)
+          : currentPoint;
+
+      const endControlPoint = getPoint(segment, 0, isRelative, currentPoint);
+      const nextPoint = getPoint(segment, 2, isRelative, currentPoint);
+      addSegmentToProfile(
+        profile,
+        new CubicBezierSegment(
+          currentPoint,
+          startControlPoint,
+          endControlPoint,
+          nextPoint,
+        ),
+      );
+      currentPoint = nextPoint;
+    } else if (command === 'a') {
+      const radius = getVector2(segment, 0);
+      const angle = getArg(segment, 2);
+      const largeArcFlag = getArg(segment, 3);
+      const sweepFlag = getArg(segment, 4);
+      const nextPoint = getPoint(segment, 5, isRelative, currentPoint);
+      addSegmentToProfile(
+        profile,
+        new ArcSegment(
+          currentPoint,
+          radius,
+          angle,
+          largeArcFlag,
+          sweepFlag,
+          nextPoint,
+        ),
+      );
+      currentPoint = nextPoint;
+    } else if (command === 'z') {
+      if (!firstPoint) continue;
+      if (currentPoint.equals(firstPoint)) continue;
+
+      addSegmentToProfile(profile, new LineSegment(currentPoint, firstPoint));
+      currentPoint = firstPoint;
+    }
+  }
+  updateMinSin(profile);
+
+  return profile;
+}

package/src/lib/curves/getPointAtDistance.ts

@@ -0,0 +1,21 @@
+import {Vector2, clamp} from '@canvas-commons/core';
+import {CurvePoint} from './CurvePoint';
+import {CurveProfile} from './CurveProfile';
+
+export function getPointAtDistance(
+  profile: CurveProfile,
+  distance: number,
+): CurvePoint {
+  const clamped = clamp(0, profile.arcLength, distance);
+  let length = 0;
+  for (const segment of profile.segments) {
+    const previousLength = length;
+    length += segment.arcLength;
+    if (length >= clamped) {
+      const relative = (clamped - previousLength) / segment.arcLength;
+      return segment.getPoint(clamp(0, 1, relative));
+    }
+  }
+
+  return {position: Vector2.zero, tangent: Vector2.up, normal: Vector2.up};
+}

package/src/lib/curves/getPolylineProfile.test.ts

@@ -0,0 +1,21 @@
+import {Vector2} from '@canvas-commons/core';
+import {describe, expect, test} from 'vitest';
+import {getPolylineProfile} from './getPolylineProfile';
+
+describe('getPolylineProfile', () => {
+  test('Correct arc length', () => {
+    const profile = getPolylineProfile(
+      [
+        Vector2.zero,
+        Vector2.zero,
+        new Vector2(100, 0),
+        new Vector2(100, 100),
+        new Vector2(0, 100),
+      ],
+      0,
+      true,
+    );
+
+    expect(profile.arcLength).toBe(400);
+  });
+});

package/src/lib/curves/getPolylineProfile.ts

@@ -0,0 +1,88 @@
+import {Vector2, clamp} from '@canvas-commons/core';
+import {CircleSegment} from './CircleSegment';
+import {CurveProfile} from './CurveProfile';
+import {LineSegment} from './LineSegment';
+
+export function getPolylineProfile(
+  points: readonly Vector2[],
+  radius: number,
+  closed: boolean,
+): CurveProfile {
+  const profile: CurveProfile = {
+    arcLength: 0,
+    segments: [],
+    minSin: 1,
+  };
+
+  if (points.length === 0) {
+    return profile;
+  }
+
+  if (closed) {
+    const middle = points[0].add(points[points.length - 1]).scale(0.5);
+    points = [middle, ...points, middle];
+  }
+
+  let last = points[0];
+  for (let i = 2; i < points.length; i++) {
+    const start = points[i - 2];
+    const center = points[i - 1];
+    const end = points[i];
+
+    const centerToStart = start.sub(center);
+    const centerToEnd = end.sub(center);
+    const startVector = centerToStart.normalized.safe;
+    const endVector = centerToEnd.normalized.safe;
+    const angleBetween = Math.acos(clamp(-1, 1, startVector.dot(endVector)));
+    const angleTan = Math.tan(angleBetween / 2);
+    const angleSin = Math.sin(angleBetween / 2);
+
+    const safeRadius = Math.min(
+      radius,
+      angleTan * centerToStart.magnitude * (i === 2 ? 1 : 0.5),
+      angleTan * centerToEnd.magnitude * (i === points.length - 1 ? 1 : 0.5),
+    );
+
+    const circleOffsetDistance = angleSin === 0 ? 0 : safeRadius / angleSin;
+    const pointOffsetDistance = angleTan === 0 ? 0 : safeRadius / angleTan;
+    const circleDistance = startVector
+      .add(endVector)
+      .scale(1 / 2)
+      .normalized.safe.scale(circleOffsetDistance)
+      .add(center);
+
+    const counter = startVector.perpendicular.dot(endVector) < 0;
+    const line = new LineSegment(
+      last,
+      center.add(startVector.scale(pointOffsetDistance)),
+    );
+    const circle = new CircleSegment(
+      circleDistance,
+      safeRadius,
+      startVector.perpendicular.scale(counter ? 1 : -1),
+      endVector.perpendicular.scale(counter ? -1 : 1),
+      counter,
+    );
+
+    if (line.arcLength > 0) {
+      profile.segments.push(line);
+      profile.arcLength += line.arcLength;
+    }
+    if (circle.arcLength > 0) {
+      profile.segments.push(circle);
+      profile.arcLength += circle.arcLength;
+    }
+
+    profile.minSin = Math.min(profile.minSin, Math.abs(angleSin));
+
+    last = center.add(endVector.scale(pointOffsetDistance));
+  }
+
+  const line = new LineSegment(last, points[points.length - 1]);
+  if (line.arcLength > 0) {
+    profile.segments.push(line);
+    profile.arcLength += line.arcLength;
+  }
+
+  return profile;
+}