Skip to content

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.ts
index 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()