Visualize Your Ideas With Code
feat(2d): add arcLength helper methods to Curve (#627)
Jacob3c7546e7a509
diff --git a/packages/2d/src/components/Curve.ts b/packages/2d/src/components/Curve.tsindex 073ab438..3c2e7405 100644--- a/packages/2d/src/components/Curve.ts+++ b/packages/2d/src/components/Curve.ts@@ -15,45 +15,142 @@ import {Shape, ShapeProps} from './Shape';export interface CurveProps extends ShapeProps {children?: Node[];+ /**+ * {@inheritDoc Curve.closed}+ */closed?: SignalValue<boolean>;+ /**+ * {@inheritDoc Curve.start}+ */start?: SignalValue<number>;+ /**+ * {@inheritDoc Curve.startOffset}+ */startOffset?: SignalValue<number>;+ /**+ * {@inheritDoc Curve.startArrow}+ */startArrow?: SignalValue<boolean>;+ /**+ * {@inheritDoc Curve.end}+ */end?: SignalValue<number>;+ /**+ * {@inheritDoc Curve.endOffset}+ */endOffset?: SignalValue<number>;+ /**+ * {@inheritDoc Curve.endArrow}+ */endArrow?: SignalValue<boolean>;+ /**+ * {@inheritDoc Curve.arrowSize}+ */arrowSize?: SignalValue<number>;}export abstract class Curve extends Shape {+ /**+ * Whether the curve should be closed.+ *+ * @remarks+ * Closed curves have their start and end points connected.+ */@initial(false)@signal()public declare readonly closed: SimpleSignal<boolean, this>;+ /**+ * A percentage from the start before which the curve should be clipped.+ *+ * @remarks+ * The portion of the curve that comes before the given percentage will be+ * made invisible.+ *+ * This property is usefully for animating the curve appearing on the screen.+ * The value of `0` means the very start of the curve (accounting for the+ * {@link startOffset}) while `1` means the very end (accounting for the+ * {@link endOffset}).+ */@initial(0)@signal()public declare readonly start: SimpleSignal<number, this>;+ /**+ * The offset in pixels from the start of the curve.+ *+ * @remarks+ * This property lets you specify where along the defined curve the actual+ * visible portion starts. For example, setting it to `20` will make the first+ * 20 pixels of the curve invisible.+ *+ * This property is useful for trimming the curve using a fixed distance.+ * If you want to animate the curve appearing on the screen, use {@link start}+ * instead.+ */@initial(0)@signal()public declare readonly startOffset: SimpleSignal<number, this>;+ /**+ * Whether to display an arrow at the start of the visible curve.+ *+ * @remarks+ * Use {@link arrowSize} to control the size of the arrow.+ */@initial(false)@signal()public declare readonly startArrow: SimpleSignal<boolean, this>;+ /**+ * A percentage from the start after which the curve should be clipped.+ *+ * @remarks+ * The portion of the curve that comes after the given percentage will be+ * made invisible.+ *+ * This property is usefully for animating the curve appearing on the screen.+ * The value of `0` means the very start of the curve (accounting for the+ * {@link startOffset}) while `1` means the very end (accounting for the+ * {@link endOffset}).+ */@initial(1)@signal()public declare readonly end: SimpleSignal<number, this>;+ /**+ * The offset in pixels from the end of the curve.+ *+ * @remarks+ * This property lets you specify where along the defined curve the actual+ * visible portion ends. For example, setting it to `20` will make the last+ * 20 pixels of the curve invisible.+ *+ * This property is useful for trimming the curve using a fixed distance.+ * If you want to animate the curve appearing on the screen, use {@link end}+ * instead.+ */@initial(0)@signal()public declare readonly endOffset: SimpleSignal<number, this>;+ /**+ * Whether to display an arrow at the end of the visible curve.+ *+ * @remarks+ * Use {@link arrowSize} to control the size of the arrow.+ */@initial(false)@signal()public declare readonly endArrow: SimpleSignal<boolean, this>;+ /**+ * Controls the size of the end and start arrows.+ *+ * @remarks+ * To make the arrows visible make sure to enable {@link startArrow} and/or+ * {@link endArrow}.+ */@initial(24)@signal()public declare readonly arrowSize: SimpleSignal<number, this>;@@ -70,12 +167,66 @@ export abstract class Curve extends Shape {public abstract profile(): CurveProfile;+ /**+ * Convert a percentage along the curve to a distance.+ *+ * @remarks+ * The returned distance is given in relation to the full curve, not+ * accounting for {@link startOffset} and {@link endOffset}.+ *+ * @param value - The percentage along the curve.+ */public percentageToDistance(value: number): number {- const {arcLength} = this.profile();+ return this.startOffset() + this.offsetArcLength() * value;+ }++ /**+ * Convert a distance along the curve to a percentage.+ *+ * @remarks+ * The distance should be given in relation to the full curve, not+ * accounting for {@link startOffset} and {@link endOffset}.+ *+ * @param value - The distance along the curve.+ */+ public distanceToPercentage(value: number): number {+ return (value - this.startOffset()) / this.offsetArcLength();+ }++ /**+ * The base arc length of this curve.+ *+ * @remarks+ * This is the entire length of this curve, not accounting for+ * {@link startOffset | the offsets}.+ */+ public baseArcLength() {+ return this.profile().arcLength;+ }++ /**+ * The offset arc length of this curve.+ *+ * @remarks+ * This is the length of the curve that accounts for+ * {@link startOffset | the offsets}.+ */+ public offsetArcLength() {const startOffset = this.startOffset();const endOffset = this.endOffset();- const realLength = arcLength - startOffset - endOffset;- return startOffset + realLength * value;+ return this.baseArcLength() - startOffset - endOffset;+ }++ /**+ * The visible arc length of this curve.+ *+ * @remarks+ * This arc length accounts for both the offset and the {@link start} and+ * {@link end} properties.+ */+ @computed()+ public arcLength() {+ return this.offsetArcLength() * Math.abs(this.start() - this.end());}@computed()