API Reference › core-geometry› Curve › LineString3d

LineString3d Class

  • A LineString3d (sometimes called a PolyLine) is a sequence of xyz coordinates that are to be joined by line segments.
  • The point coordinates are stored in a GrowableXYZArray, not as full point objects.
  • The parameterization of "fraction along" is
    • In a linestring with N segments (i.e. N+1 points), each segment (regardless of physical length) occupies the same fraction (1/N) of the 0-to-1 fraction space.
    • Within segment i, the fraction interval i/N to (i+1)/N is mapped proportionally to the segment
    • Note that this fraction is therefore NOT fraction of true distance along.
    • Use moveSignedDistanceFromFraction to do true-length evaluations.

Extends

Implements

Methods

Name Description
addClosurePoint(): void If the linestring is not already closed, add a closure point.  
addDerivative(vector: Vector3d): void Append a derivative to the derivative array  
addFraction(fraction: number): void Append a fraction to the fractions array.  
addMappedStrokesToLineString3D(map: StrokeCountMap, destLinestring: LineString3d): number Evaluate strokes at fractions indicated in a StrokeCountMap.  
addPoint(point: Point3d): void Add a point to the linestring.  
addPoints(...points: any[]): void Add copies of points to the linestring.  
addPointXYZ(x: number, y: number, z: number = 0): void Add a point to the linestring.  
addSteppedPoints(source: GrowableXYZArray, pointIndex0: number, step: number, numAdd: number): void Add points accessed by index in a GrowableXYZArray, with a specified index step.  
addSurfaceNormal(vector: Vector3d): void Append a surface normal to the surface normal array.  
addUVParam(uvParam: XAndY): void Append a uv coordinate to the uvParams array  
addUVParamAsUV(u: number, v: number): void Append a uv coordinate to the uvParams array  
announceClipIntervals(clipper: Clipper, announce?: AnnounceNumberNumberCurvePrimitive): boolean Find intervals of this CurvePrimitive that are interior to a clipper.  
appendFractionalStrokePoints(curve: CurvePrimitive, numStrokes: number, fraction0: number = 0, fraction1: number = 1, include01: boolean = true): void Evaluate a curve at uniform fractions.  
appendFractionToPoint(curve: CurvePrimitive, fraction: number): void Append a suitable evaluation of a curve.  
appendInterpolatedStrokePoints(numStrokes: number, point0: Point3d, point1: Point3d, include01: boolean): void Append points constructed as interpolation between two points.  
appendPlaneIntersectionPoints(plane: PlaneAltitudeEvaluator, result: CurveLocationDetail[]): number Find intersections with a plane.  
appendStrokePoint(point: Point3d, fraction?: number): void Append (clone of) one point.  
clear(): void Clear all array data:  
clone(): LineString3d Return a clone of this linestring.  
clonePartialCurve(fractionA: number, fractionB: number): LineString3d Return a LineString which is a portion of this curve.  
cloneTransformed(transform: Transform): LineString3d Clone this linestring and apply the transform to the clone points.  
closestPoint(spacePoint: Point3d, extend: VariantCurveExtendParameter = false, result?: CurveLocationDetail): CurveLocationDetail Find the point on the linestring (including its segment interiors) that is closest to spacePoint.  
collectCurvePrimitivesGo(collectorArray: CurvePrimitive[], _smallestPossiblePrimitives: boolean, explodeLinestrings: boolean = false): void Return an array containing only the curve primitives.  
computeAndAttachRecursiveStrokeCounts(options?: StrokeOptions, parentStrokeMap?: StrokeCountMap): void Compute individual segment stroke counts.  
computeStrokeCountForOptions(options?: StrokeOptions): number Return the stroke count required for given options.  
computeUVFromXYZTransform(transform: Transform): void Compute uvParams array as (xy parts of) a linear transform of the xyz coordinates  
constructOffsetXY(offsetDistanceOrOptions: number | OffsetOptions): CurvePrimitive | CurvePrimitive[] | undefined Construct an offset of each segment as viewed in the xy-plane (ignoring z).  
curveLength(): number Sum the lengths of segments within the linestring  
curveLengthBetweenFractions(fraction0: number, fraction1: number): number Sum the lengths of segments between fractional positions on a linestring.  
derivativeAt(i: number, result?: Vector3d): Vector3d | undefined If i is a valid index, return that stored derivative vector.  
dispatchToGeometryHandler(handler: GeometryHandler): any Second step of double dispatch: call handler.handleLineString3d(this)  
emitStrokableParts(handler: IStrokeHandler, options?: StrokeOptions): void Emit strokable parts of the curve to a caller-supplied handler.  
emitStrokes(dest: LineString3d, options?: StrokeOptions): void Emit strokes to caller-supplied linestring  
endPoint(result?: Point3d): Point3d Evaluate the end point of the linestring.  
ensureEmptyDerivatives(): GrowableXYZArray Ensure that the derivatives array exists with length 0 but at least the capacity of the point array.  
ensureEmptyFractions(): GrowableFloat64Array Ensure that the fractions array exists with length 0 but at least the capacity of the point array.  
ensureEmptyNormalIndices(): GrowableFloat64Array Ensure that the normalIndices array exists with length 0 but at least the capacity of the point array.  
ensureEmptyPointIndices(): GrowableFloat64Array Ensure that the pointIndices array exists with length 0 but at least the capacity of the point array.  
ensureEmptySurfaceNormals(): GrowableXYZArray Ensure that the surfaceNormals array exists with length 0 but at least the capacity of the point array.  
ensureEmptyUVIndices(): GrowableFloat64Array Ensure that the uvIndices array exists with length 0 but at least the capacity of the point array.  
ensureEmptyUVParams(): GrowableXYArray Ensure that the uvParams array exists with length 0 but at least the capacity of the point array.  
extendRange(rangeToExtend: Range3d, transform?: Transform): void Extend rangeToExtend to include all points of this linestring.  
fractionToFrenetFrame(fraction: number, result?: Transform): Transform Return a Frenet frame, using nearby points to estimate a plane.  
fractionToPoint(fraction: number, result?: Point3d): Point3d Evaluate a point a fractional position along this linestring.  
fractionToPointAnd2Derivatives(fraction: number, result?: Plane3dByOriginAndVectors): Plane3dByOriginAndVectors Return point and derivative at fraction, with 000 second derivative.  
fractionToPointAndDerivative(fraction: number, result?: Ray3d): Ray3d Evaluate a point a fractional position and derivative with respect to fraction along this linestring.  
getIndexedSegment(index: number, result?: LineSegment3d): LineSegment3d | undefined Return (if possible) a specific segment of the linestring  
getUncheckedIndexedSegment(index: number, result?: LineSegment3d): LineSegment3d Return a specific segment of the linestring.  
globalFractionToSegmentIndexAndLocalFraction(globalFraction: number): { fraction: number, index: number } Convert a global linestring fraction to a segment index and local fraction.  
isAlmostEqual(other: GeometryQuery): boolean Test if each point of this linestring isAlmostEqual with corresponding point in other.  
isInPlane(plane: Plane3dByOriginAndUnitNormal): boolean Test if all points of the linestring are in a plane.  
isPhysicallyClosedCurve(tolerance: number = Geometry.smallMetricDistance, xyOnly: boolean = false): boolean Whether the start and end points are defined and within tolerance.  
isSameGeometryClass(other: GeometryQuery): boolean test if other is an instance of LineString3d  
moveSignedDistanceFromFraction(startFraction: number, signedDistance: number, allowExtension: "false", result?: CurveLocationDetail): CurveLocationDetail * Implementation of CurvePrimitive.moveSignedDistanceFromFraction.  
numEdges(): number Return the number of edges in this linestring.  
numPoints(): number Return the number of points in this linestring.  
pointAt(i: number, result?: Point3d): Point3d | undefined If i is a valid index, return that point.  
pointAtUnchecked(i: number, result?: Point3d): Point3d Return the point for the given index.  
popPoint(): void Eliminate (but do not return!!) the final point of the linestring  
projectedParameterRange(ray: Vector3d | Ray3d, lowHigh?: Range1d): Range1d | undefined Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters  
quickLength(): number Sum lengths of segments in the linestring.  
quickUnitNormal(result?: Vector3d): Vector3d | undefined Compute and normalize cross product among 3 points on the linestring.  
rangeBetweenFractions(fraction0: number, fraction1: number, transform?: Transform): Range3d Compute the range of points between fractional positions on the linestring.  
removeDuplicatePoints(tolerance: number = Geometry.smallMetricDistance): void Compress out duplicate points (according to point.isAlmostEqual)  
reverseInPlace(): void Reverse the points within the linestring.  
segmentIndexAndLocalFractionToGlobalFraction(index: number, localFraction: number): number Convert a segment index and local fraction to a global linestring fraction.  
setFrom(other: LineString3d): void Copy coordinate data from another linestring.  
setFromJSON(json?: any): void Set point coordinates from a json array, e.g.  
startPoint(result?: Point3d): Point3d Evaluate the start point of the linestring.  
surfaceNormalAt(i: number, result?: Vector3d): Vector3d | undefined If i is a valid index, return that stored surfaceNormal vector.  
toJSON(): XYZProps[] Convert an LineString3d to a JSON object.  
tryTransformInPlace(transform: Transform): boolean Apply transform to each point of this linestring.  
vectorBetween(i: number, j: number, result?: Vector3d): Vector3d | undefined If i and j are both valid indices, return the vector from point i to point j  
convertLocalToGlobalDetail(detail: CurveLocationDetail, segmentIndex: number, numSegment: number, parent?: LineString3d, child?: CurveLocationDetail): CurveLocationDetail Static Convert the segment detail to a linestring detail:  
create(...points: any[]): LineString3d Static Create a linestring, using flex length arg list and any typical combination of points such as  
createArrayOfLineString3d(data: MultiLineStringDataVariant): LineString3d[] Static Convert variant point data to a single level array of linestrings.  
createCapture(points: GrowableXYZArray): LineString3d Static Create a linestring, capturing the given GrowableXYZArray as the points.  
createFloat64Array(xyzData: Float64Array): LineString3d Static Create a LineString3d from xyz coordinates packed in a Float64Array  
createForStrokes(capacity: number = 0, options: StrokeOptions): LineString3d Static * options.needParams triggers creation of fraction array and uvParams array.  
createIndexedPoints(points: Point3d[], index: number[], addClosure: boolean = false): LineString3d Static Create a linestring, taking points at specified indices from an array of points.  
createPoints(points: Point3d[]): LineString3d Static Create a linestring from an array of points.  
createRectangleXY(point0: Point3d, ax: number, ay: number, closed: boolean = true): LineString3d Static Create the linestring for a rectangle parallel to the xy plane.  
createRegularPolygonXY(center: Point3d, edgeCount: number, radius: number, radiusToVertices: boolean = true): LineString3d Static Create a regular polygon centered  
createXY(points: Readonly<WritableXAndY>[], z: number, enforceClosure: boolean = false): LineString3d Static Create a linestring from XAndY points, with a specified z applied to all.  
fromJSON(json?: any): LineString3d Static Construct a new linestring.  
mapGlobalToLocalFraction(globalFraction: number, numSegment: number): { fraction: number, index: number } Static Convert a global linestring fraction to a segment index and local fraction.  
mapLocalToGlobalFraction(index: number, localFraction: number, numSegment: number): number Static Convert a segment index and local fraction to a global linestring fraction.  

Inherited methods

Name Inherited from Description
allTangents(spacePoint: Point3d, options?: TangentOptions): CurveLocationDetail[] | undefined Inherited CurvePrimitive Return all points P on the curve such that the line containing spacePoint and P is tangent to the curve in
closestPointXY(spacePoint: Point3d, extend: VariantCurveExtendParameter = false, result?: CurveLocationDetail): CurveLocationDetail | undefined Inherited CurvePrimitive Search for a point on the curve that is closest to spacePoint, ignoring z-coordinates.
closestTangent(spacePoint: Point3d, options?: TangentOptions): CurveLocationDetail | undefined Inherited CurvePrimitive Return the point P on the curve such that the line containing spacePoint and P is tangent to the curve in
collectCurvePrimitives(collectorArray?: CurvePrimitive[], smallestPossiblePrimitives: boolean = false, explodeLinestrings: boolean = false): CurvePrimitive[] Inherited CurvePrimitive Return an array containing only the curve primitives.
curveLengthWithFixedIntervalCountQuadrature(fraction0: number, fraction1: number, numInterval: number, numGauss: number = 5): number Inherited CurvePrimitive Run an integration (with a default Gaussian quadrature) with a fixed fractional step
emitTangents(spacePoint: Point3d, announceTangent: (tangent: CurveLocationDetail) => any, options?: TangentOptions): void Inherited CurvePrimitive Announce all points P on the curve such that the line containing spacePoint and P is tangent to the curve in
fractionAndDistanceToPointOnTangent(fraction: number, distance: number): Point3d Inherited CurvePrimitive Construct a point extrapolated along tangent at fraction.
fractionToCurvature(fraction: number): number | undefined Inherited CurvePrimitive Returns the (absolute) curvature magnitude.
fractionToPointAndUnitTangent(fraction: number, result?: Ray3d): Ray3d Inherited CurvePrimitive Returns a ray whose origin is the curve point and direction is the unit tangent.
fractionToSignedXYRadiusOfCurvature(fraction: number): number Inherited CurvePrimitive Construct signed distance from a point on the planar curve to its center of curvature (in xy only).
getFractionToDistanceScale(): number | undefined Inherited CurvePrimitive If the curve primitive has distance-along-curve strictly proportional to curve fraction, return the scale factor.
moveSignedDistanceFromFractionGeneric(startFraction: number, signedDistance: number, allowExtension: boolean, result?: CurveLocationDetail): CurveLocationDetail Protected Inherited CurvePrimitive Generic algorithm to search for point at signed distance from a fractional startPoint.
range(transform?: Transform, result?: Range3d): Range3d Inherited CurvePrimitive Return the range of the entire GeometryQuery tree.
rangeBetweenFractionsByClone(fraction0: number, fraction1: number, transform?: Transform): Range3d Inherited CurvePrimitive Returns a high accuracy range of the curve between fractional positions using clonePartialCurve.
rangeBetweenFractionsByCount(fraction0: number, fraction1: number, count: number, transform?: Transform, extrapolationFactor: number = 0.0): Range3d Inherited CurvePrimitive Returns an approximate range based on a fixed number of evaluations.
reverse(): this Inherited CurvePrimitive Call reverseInPlace and return the instance.
tryTranslateInPlace(dx: number, dy: number = 0.0, dz: number = 0.0): boolean Inherited CurvePrimitive Try to move the geometry by dx,dy,dz.
areAlmostEqual(a: GeometryQuery, b: GeometryQuery): boolean Static Inherited CurvePrimitive Apply instance method isAlmostEqual if both are defined.
computeScaledTolerance(geom: GeometryQuery | GeometryQuery[], options?: ScaledToleranceOptions): number Static Inherited CurvePrimitive Compute a distance tolerance appropriate for comparing the coordinates of geom.
installStrokeCountMap(curve: CurvePrimitive, curveMap: StrokeCountMap, parentMap?: StrokeCountMap): void Static Inherited CurvePrimitive Final install step to save curveMap in curve.
scaleToleranceForGeometry(geom: GeometryQuery | GeometryQuery[], distanceTolerance: number, options?: ScaledToleranceOptions): number Static Inherited CurvePrimitive Scale the given distance tolerance as appropriate for comparing the coordinates of geom.

Properties

Name Type Description
curvePrimitiveType Readonly "lineString" String name for schema properties  
fractions Accessor ReadOnly GrowableFloat64Array | undefined Return array of fraction parameters.  
isExtensibleFractionSpace Accessor ReadOnly boolean A LineString3d extends along its first and final segments.  
isPhysicallyClosed Accessor ReadOnly boolean Returns true if first and last points are within metric tolerance.  
normalIndices Accessor ReadOnly GrowableFloat64Array | undefined Return the (optional) array of normal indices.  
packedDerivatives Accessor ReadOnly GrowableXYZArray | undefined Return the (optional) array of derivatives.  
packedPoints Accessor ReadOnly GrowableXYZArray Return (reference to) point data in packed GrowableXYZArray.  
packedSurfaceNormals Accessor ReadOnly GrowableXYZArray | undefined Return the (optional) array of surface normals.  
packedUVParams Accessor ReadOnly GrowableXYArray | undefined Return the (optional) array of uv parameters.  
paramIndices Accessor ReadOnly GrowableFloat64Array | undefined Return the (optional) array of uv parameter indices.  
pointIndices Accessor ReadOnly GrowableFloat64Array | undefined Return the (optional) array of point indices.  
points Accessor ReadOnly Point3d[] Return the points array (cloned).  

Inherited properties

Name Type Inherited from Description
children Accessor Inherited ReadOnly GeometryQuery[] | undefined CurvePrimitive Return GeometryQuery children for recursive queries.
* leaf classes do not need to implement.
geometryCategory Readonly Inherited "curvePrimitive" CurvePrimitive String name for schema properties
parent Inherited any | undefined CurvePrimitive Data attached by various algorithms (e.g.
strokeData Inherited StrokeCountMap | undefined CurvePrimitive Data attached during stroking for facets.

Defined in

Last Updated: 24 September, 2026