ducjs 1.0.0

package/dist/utils/math/index.d.ts

@@ -0,0 +1,323 @@
+export * from "./geometry";
+export * from "./bbox";
+export * from "./algebra";
+export * from "./random";
+import type { NullableGridSize, Zoom } from "ducjs/types";
+import { Scope, ScopedValue } from "ducjs/types";
+import type { DucElement, DucLine, DucLinearElement, DucLinearLikeElement, DucPoint, NonDeleted } from "ducjs/types/elements";
+import type { Bounds, GeometricPoint, GeometricVector, Percentage, Radian } from "ducjs/types/geometryTypes";
+import { Heading } from "ducjs/types/geometryTypes";
+import { SupportedMeasures } from "ducjs/technical/scopes";
+export declare const getRadianFromDegrees: (degrees: number) => Radian;
+export declare const getDegreesFromRadian: (radian: Radian) => number;
+export declare const getPercentageValueFromPercentage: (value: number) => Percentage;
+export declare const getPercentageFromPercentage: (percentage: Percentage) => number;
+export declare const med: (A: number[], B: number[]) => number[];
+/**
+ * Rotates a point (x, y) around another point (cx, cy) by a given angle.
+ * Returns the rotated point as a Point object.
+ */
+export declare const rotate: (x: number, y: number, cx: number, cy: number, angle: number) => GeometricPoint;
+/**
+ * Rotates a Point around another Point by a given angle.
+ * Returns the rotated point as a Point object.
+ */
+export declare const rotatePoint: (point: GeometricPoint, center: GeometricPoint, angle: number) => GeometricPoint;
+export declare const getSizeFromPoints: (points: readonly GeometricPoint[]) => {
+    width: ScopedValue;
+    height: ScopedValue;
+};
+/** @arg dimension, 0 for rescaling only x, 1 for y */
+export declare const rescalePoints: (dimension: "x" | "y", newSize: ScopedValue, points: readonly DucPoint[], normalize: boolean, elementScope: SupportedMeasures, currentScope: Scope) => DucPoint[];
+export declare const rescaleLines: (dimension: "x" | "y", newSize: ScopedValue, lines: readonly DucLine[], points: readonly DucPoint[], normalize: boolean, elementScope: SupportedMeasures, currentScope: Scope) => DucLine[];
+/**
+ * Calculates the distance from a point to a line segment
+ * @param point The point to check distance from
+ * @param start Start point of line segment
+ * @param end End point of line segment
+ * @returns Distance from point to line segment
+ */
+export declare function distanceToLineSegment(point: GeometricPoint, start: GeometricPoint, end: GeometricPoint): number;
+/**
+ * Calculates the distance from a point to a cubic Bezier curve segment
+ * @param point The point to check distance from
+ * @param start Start point of Bezier curve
+ * @param end End point of Bezier curve
+ * @param cp1 First control point
+ * @param cp2 Second control point
+ * @param numSamples Number of samples to use for approximation
+ * @returns Approximate distance from point to Bezier curve
+ */
+export declare function distanceToCurveSegment(point: GeometricPoint, start: GeometricPoint, end: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, numSamples?: number): number;
+/**
+ * Samples points along a cubic Bezier curve using De Casteljau's algorithm
+ * More precise than the sampleBezierCurve in bounds.ts, but used only for distance calculations
+ */
+export declare function sampleBezierCurve(start: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, end: GeometricPoint, numSamples: number): GeometricPoint[];
+/**
+ * Evaluates a point at parameter t on the cubic Bezier curve
+ */
+export declare function evaluateBezier(p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint, t: number): GeometricPoint;
+/**
+ * Calculates the approximate complexity of a Bezier curve to determine sampling rate
+ */
+export declare function calculateCurveComplexity(start: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, end: GeometricPoint): number;
+/**
+ * Helper function to calculate the distance from a point to a line
+ */
+export declare function distanceFromPointToLine(point: GeometricPoint, lineStart: GeometricPoint, lineEnd: GeometricPoint): number;
+/**
+ * Adaptive sampling for bounds (from bounds.ts)
+ * This is different from the distance version above.
+ */
+export declare function sampleBezierCurveForBounds(start: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, end: GeometricPoint, numSamples?: number): GeometricPoint[];
+/**
+ * Calculate approximate curve complexity based on control point positions (from bounds.ts)
+ */
+export declare function calculateCurvature(start: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, end: GeometricPoint): number;
+/**
+ * Get a point on a cubic bezier at t (from bounds.ts)
+ */
+export declare function getBezierPoint(start: GeometricPoint, cp1: GeometricPoint, cp2: GeometricPoint, end: GeometricPoint, t: number): GeometricPoint;
+/**
+ * Quadratic bezier bounding box (from bounds.ts)
+ * Enhanced version that handles edge cases better
+ */
+export declare function getQuadraticBezierBoundingBox(p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint): {
+    minX: ScopedValue;
+    minY: ScopedValue;
+    maxX: ScopedValue;
+    maxY: ScopedValue;
+};
+/**
+ * Cubic bezier bounding box (from bounds.ts)
+ * Enhanced version that handles edge cases better
+ */
+export declare function getCubicBezierBoundingBox(p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint): {
+    minX: ScopedValue;
+    minY: ScopedValue;
+    maxX: ScopedValue;
+    maxY: ScopedValue;
+};
+/**
+ * Cubic bezier curve bound (returns Bounds tuple, from bounds.ts)
+ */
+export declare function getCubicBezierCurveBound(p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint): [number, number, number, number];
+export declare const isPointCurved: (element: DucLinearElement, pointIndex: number) => boolean;
+/**
+ * Gets the bezier handles for a point from the lines array
+ */
+export declare const getPointHandles: (element: DucLinearElement, pointIndex: number) => {
+    handleIn?: GeometricPoint;
+    handleOut?: GeometricPoint;
+};
+/**
+ * Gets connected point indices from the lines array
+ */
+export declare const getConnectedPoints: (element: DucLinearElement, pointIndex: number) => number[];
+export declare function pointRotateRads<Point extends GeometricPoint>(point: GeometricPoint, center: GeometricPoint, angle: number): Point;
+export declare const distanceSq: (p1: GeometricPoint, p2: GeometricPoint) => number;
+export declare const distanceToLineSegmentSq: (p: GeometricPoint, a: GeometricPoint, b: GeometricPoint) => number;
+export declare const sampleQuadratic: (p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, samples: GeometricPoint[], depth: number, maxDepth: number, toleranceSq: number) => void;
+export declare const sampleCubic: (p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint, samples: GeometricPoint[], depth: number, maxDepth: number, toleranceSq: number) => void;
+/**
+ * Adjusts x and y coordinates based on rotation and deltas.
+ * Returns the adjusted coordinates as a Point object.
+ */
+export declare const adjustXYWithRotation: (sides: {
+    n?: boolean;
+    e?: boolean;
+    s?: boolean;
+    w?: boolean;
+}, x: number, y: number, angle: number, deltaX1: number, deltaY1: number, deltaX2: number, deltaY2: number) => GeometricPoint;
+/**
+ * Finds a point on a path.
+ * Returns an object with x, y, and the segment index if found, else null.
+ */
+export declare const getPointOnAPath: (point: GeometricPoint, path: GeometricPoint[]) => {
+    x: number;
+    y: number;
+    segment: number;
+} | null;
+/**
+ * Calculates the Euclidean distance between two points.
+ */
+export declare const distance2d: (x1: number, y1: number, x2: number, y2: number) => number;
+/**
+ * Calculates the squared Euclidean distance between two Points.
+ */
+export declare const distanceSq2d: (p1: GeometricPoint, p2: GeometricPoint) => number;
+/**
+ * Calculates the center point between two Points.
+ */
+export declare const centerPoint: (a: GeometricPoint, b: GeometricPoint) => GeometricPoint;
+/**
+ * Checks if the first and last point are close enough to be considered a loop.
+ */
+export declare const isPathALoop: (points: DucLinearElement["points"], 
+/** Supply if you want the loop detection to account for current zoom */
+zoomValue: Zoom["scoped"] | undefined, elementScope: Scope, currentScope: Scope) => boolean;
+/**
+ * Determines if a Point is inside a Polygon defined by an array of Points.
+ */
+export declare const isPointInPolygon: (points: GeometricPoint[], x: number, y: number) => boolean;
+/**
+ * Returns whether `q` lies inside the segment/rectangle defined by `p` and `r`.
+ * This is an approximation to "does `q` lie on a segment `pr`" check.
+ */
+export declare const isPointWithinBounds: (p: GeometricPoint, q: GeometricPoint, r: GeometricPoint) => boolean;
+/**
+ * Rounds a point to the nearest grid point based on gridSize.
+ */
+export declare const getGridPoint: (x: number, y: number, gridSize: NullableGridSize) => GeometricPoint;
+/**
+ * Calculates a point on a Bezier curve at parameter t.
+ * Returns the point as a Point object.
+ */
+export declare const getBezierXY: (p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint, t: number) => GeometricPoint;
+/**
+ * Checks if two Points are equal based on their x and y coordinates.
+ */
+export declare const arePointsEqual: (p1: GeometricPoint, p2: GeometricPoint, threshold?: number) => boolean;
+/**
+ * Checks if an angle is a right angle (with floating point tolerance).
+ */
+export declare const isRightAngle: (angle: number) => boolean;
+/**
+ * Converts radians to degrees.
+ */
+export declare const radianToDegree: (r: number) => number;
+/**
+ * Converts degrees to radians.
+ */
+export declare const degreeToRadian: (d: number) => number;
+/**
+ * Given two ranges, returns if the two ranges overlap with each other.
+ * e.g. [1, 3] overlaps with [2, 4] while [1, 3] does not overlap with [4, 5]
+ */
+export declare const rangesOverlap: ([a0, a1]: [number, number], [b0, b1]: [number, number]) => boolean;
+/**
+ * Given two ranges, returns the intersection of the two ranges if any.
+ * e.g. the intersection of [1, 3] and [2, 4] is [2, 3]
+ */
+export declare const rangeIntersection: (rangeA: [number, number], rangeB: [number, number]) => [number, number] | null;
+/**
+ * Checks if a value is within a range [min, max].
+ */
+export declare const isValueInRange: (value: number, min: number, max: number) => boolean;
+/**
+ * Translates a Point by a given Vector.
+ */
+export declare const translatePoint: (p: GeometricPoint, v: GeometricVector) => GeometricPoint;
+/**
+ * Scales a Vector by a scalar.
+ */
+export declare const scaleVector: (v: GeometricVector, scalar: number) => GeometricVector;
+/**
+ * Converts a Point to a Vector relative to an origin.
+ */
+export declare const pointToVector: (p: GeometricPoint, origin?: GeometricPoint) => GeometricVector;
+export declare const vectorToPoint: (v: GeometricVector, origin?: GeometricPoint) => GeometricPoint;
+export declare const headingToPoint: (heading: Heading) => GeometricPoint;
+/**
+ * Scales a Point from a midpoint by a multiplier.
+ */
+export declare const scalePointFromOrigin: (p: GeometricPoint, mid: GeometricPoint, multiplier: number) => GeometricPoint;
+/**
+ * Determines if a Point is inside a Triangle defined by three Points.
+ */
+export declare const PointInTriangle: (pt: GeometricPoint, v1: GeometricPoint, v2: GeometricPoint, v3: GeometricPoint) => boolean;
+/**
+ * Calculates the squared magnitude of a Vector.
+ */
+export declare const magnitudeSq: (vector: GeometricVector) => number;
+/**
+ * Calculates the magnitude of a Vector.
+ */
+export declare const magnitude: (vector: GeometricVector) => number;
+/**
+ * Normalizes a Vector to unit length.
+ */
+export declare const normalize: (vector: GeometricVector) => GeometricVector;
+/**
+ * Adds two Vectors.
+ */
+export declare const addVectors: (vec1: Readonly<GeometricVector>, vec2: Readonly<GeometricVector>) => GeometricVector;
+/**
+ * Subtracts vec2 from vec1.
+ */
+export declare const subtractVectors: (vec1: Readonly<GeometricVector>, vec2: Readonly<GeometricVector>) => GeometricVector;
+/**
+ * Checks if a Point is inside given Bounds.
+ */
+export declare const pointInsideBounds: (p: GeometricPoint, bounds: Bounds) => boolean;
+/**
+ * Get the axis-aligned bounding box for a given element.
+ */
+export declare const aabbForElement: (element: Readonly<DucElement>, offset?: [number, number, number, number]) => Bounds;
+type PolarCoords = [number, number];
+/**
+ * Returns the polar coordinates for the given cartesian point represented by
+ * (x, y) for the center point 0,0 where the first number returned is the radius,
+ * the second is the angle in radians.
+ */
+export declare const carthesian2Polar: ({ x, y }: GeometricPoint) => PolarCoords;
+/**
+ * Angles are in radians and centered on 0, 0. Zero radians on a 1 radius circle
+ * corresponds to (1, 0) carthesian coordinates (point), i.e. to the "right".
+ */
+type SymmetricArc = {
+    radius: number;
+    startAngle: number;
+    endAngle: number;
+};
+/**
+ * Determines if a carthesian point lies on a symmetric arc, i.e. an arc which
+ * is part of a circle contour centered on 0, 0.
+ */
+export declare const isPointOnSymmetricArc: ({ radius: arcRadius, startAngle, endAngle }: SymmetricArc, point: GeometricPoint) => boolean;
+/**
+ * Gets the center point for given Bounds.
+ */
+export declare const getCenterForBounds: (bounds: Bounds) => GeometricPoint;
+/**
+ * Gets the center point for a DucElement.
+ */
+export declare const getCenterForElement: (element: DucElement) => GeometricPoint;
+/**
+ * Determines if two axis-aligned bounding boxes overlap.
+ */
+export declare const aabbsOverlapping: (a: Bounds, b: Bounds) => boolean;
+/**
+ * Clamps a value between min and max.
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Rounds a value to a specified precision.
+ */
+export declare const round: (value: number, precision: number) => number;
+export declare const fastRound: (num: number) => number;
+export declare const polygonIncludesPointNonZero: <Point extends [number, number]>(point: Point, polygon: Point[]) => boolean;
+export declare const reverseExponent: (num: number) => number;
+/**
+ * Retrieves control points for a Bezier curve.
+ */
+export declare const getControlPointsForBezierCurve: (element: NonDeleted<DucLinearLikeElement>, endPoint: GeometricPoint) => (GeometricPoint)[] | null;
+/**
+ * Gets points along a Bezier curve for better accuracy.
+ */
+export declare const getPointsInBezierCurve: (element: NonDeleted<DucLinearLikeElement>, endPoint: GeometricPoint) => GeometricPoint[];
+/**
+ * Calculates the arc lengths of a Bezier curve.
+ */
+export declare const getBezierCurveArcLengths: (element: NonDeleted<DucLinearLikeElement>, endPoint: GeometricPoint) => number[];
+/**
+ * Calculates the total length of a Bezier curve.
+ */
+export declare const getBezierCurveLength: (element: NonDeleted<DucLinearLikeElement>, endPoint: GeometricPoint) => number;
+/**
+ * Maps an interval to the corresponding t parameter on the Bezier curve based on length.
+ */
+export declare const mapIntervalToBezierT: (element: NonDeleted<DucLinearLikeElement>, endPoint: GeometricPoint, interval: number) => number;
+export declare const sampleCubicBezier: (p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, p3: GeometricPoint, t: number) => GeometricPoint;
+export declare const sampleQuadraticBezier: (p0: GeometricPoint, p1: GeometricPoint, p2: GeometricPoint, t: number) => GeometricPoint;