## 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.

### Methods

Name Description
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.
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.
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
appendFractionToPoint(curve: CurvePrimitive, fraction: number): void Append a suitable evaluation of a curve ..
appendFractionalStrokePoints(curve: CurvePrimitive, numStrokes: number, fraction0: number = 0, fraction1: number = 1, include01: boolean = true): void Evaluate a curve at uniform fractions.
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(): Return a clone of this linestring.
clonePartialCurve(fractionA: number, fractionB: number): Return a LineString which is a portion of this curve.
cloneTransformed(transform: Transform): Clone this linestring and apply the transform to the clone points.
closestPoint(spacePoint: Point3d, extend: VariantCurveExtendParameter, result?: 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): undefined | CurvePrimitive | CurvePrimitive[] 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): undefined | Vector3d 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(): evaluate the end point of the linestring.
ensureEmptyDerivatives(): Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.
ensureEmptyFractions(): Ensure that the fraction array exists with no fractions but at least the capacity of the point array.
ensureEmptyNormalIndices(): Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.
ensureEmptyPointIndices(): Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.
ensureEmptySurfaceNormals(): Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.
ensureEmptyUVIndices(): Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.
ensureEmptyUVParams(): Ensure that the parameter array exists with no points 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): Return a frenet frame, using nearby points to estimate a plane.
fractionToPoint(fraction: number, result?: Point3d): Evaluate a point a fractional position along this linestring.
fractionToPointAnd2Derivatives(fraction: number, result?: Plane3dByOriginAndVectors): Return point and derivative at fraction, with 000 second derivative.
fractionToPointAndDerivative(fraction: number, result?: Ray3d): Evaluate a point a fractional position and derivative with respect to fraction along this linestring.
getIndexedSegment(index: number): undefined | LineSegment3d Return (if possible) a specific segment of the linestring
globalFractionToSegmentIndexAndLocalFraction(globalFraction: number): { fraction: number, index: number } Convert a global 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(): boolean Test if all points of the linestring are in a plane.
isSameGeometryClass(other: GeometryQuery): boolean test if other is an instance of LineString3d
moveSignedDistanceFromFraction(startFraction: number, signedDistance: number, allowExtension: undefined, result?: CurveLocationDetail): * Implementation of CurvePrimitive.moveSignedDistanceFromFraction.
numPoints(): number Return the number of points in this linestring.
pointAt(i: number, result?: Point3d): undefined | Point3d If i is a valid index, return that point.
popPoint(): void Eliminate (but do not return!!) the final point of the linestring
projectedParameterRange(ray: Vector3d | Ray3d, lowHigh?: Range1d): undefined | Range1d Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of projection.
quickLength(): number sum lengths of segments in the linestring.
quickUnitNormal(result?: Vector3d): undefined | Vector3d compute and normalize cross product among 3 points on the linestring.
rangeBetweenFractions(fraction0: number, fraction1: number, transform?: Transform): 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 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(): evaluate the start point of the linestring.
surfaceNormalAt(i: number, result?: Vector3d): undefined | Vector3d If i is a valid index, return that stored surfaceNormal vector.
toJSON(): any 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): undefined | Vector3d If i and j are both valid indices, return the vector from point i to point j
create(...points: any[]): Static Create a linestring, using flex length arg list and any typical combination of points such as
createArrayOfLineString3d(): Static convert variant point data to a single level array of linestrings.
createCapture(points: GrowableXYZArray): Static Create a linestring, capturing the given GrowableXYZArray as the points.
createFloat64Array(xyzData: Float64Array): Static Create a LineString3d from xyz coordinates packed in a Float64Array
createForStrokes(capacity: number = 0, options: undefined | StrokeOptions): Static * options.needParams triggers creation of fraction array and uvParams array.
createIndexedPoints(points: Point3d[], index: number[], addClosure: boolean = false): Static Create a linestring, taking points at specified indices from an array of points.
createPoints(points: Point3d[]): Static Create a linestring from an array of points.
createRectangleXY(point0: Point3d, ax: number, ay: number, closed: boolean = true): Static Create the linestring for a rectangle parallel to the xy plane.
createRegularPolygonXY(center: Point3d, edgeCount: number, radius: number, radiusToVertices: boolean = true): Static Create a regular polygon centered
createXY(points: Readonly<WritableXAndY>[], z: number, enforceClosure: boolean = false): Static Create a linestring from XAndY points, with a specified z applied to all.
fromJSON(json?: any): Static construct a new linestring.

### Inherited methods

Name Inherited from Description
collectCurvePrimitives(collectorArray?: CurvePrimitive[], smallestPossiblePrimitives: boolean = false, explodeLinestrings: boolean = false): CurvePrimitive Return an array containing only the curve primitives.
curveLengthWithFixedIntervalCountQuadrature(fraction0: number, fraction1: number, numInterval: number, numGauss: number = 5): number CurvePrimitive * Run an integration (with a default gaussian quadrature) with a fixed fractional step
fractionAndDistanceToPointOnTangent(fraction: number, distance: number): CurvePrimitive Construct a point extrapolated along tangent at fraction.
fractionToCurvature(fraction: number): undefined | number CurvePrimitive Returns the (absolute) curvature magnitude.
fractionToPointAndUnitTangent(fraction: number, result?: Ray3d): CurvePrimitive Returns a ray whose origin is the curve point and direction is the unit tangent.
fractionToSignedXYRadiusOfCurvature(fraction: number): number CurvePrimitive Construct signed distance from a point on the curve to its center of curvature (in xy only).
getFractionToDistanceScale(): undefined | number 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): Protected CurvePrimitive Generic algorithm to search for point at signed distance from a fractional startPoint.
range(transform?: Transform, result?: Range3d): CurvePrimitive return the range of the entire (tree) GeometryQuery
rangeBetweenFractionsByClone(fraction0: number, fraction1: number, transform?: Transform): CurvePrimitive Returns a (high accuracy) range of the curve between fractional positions
rangeBetweenFractionsByCount(fraction0: number, fraction1: number, count: number, transform?: Transform, extrapolationFactor: number = 0.0): CurvePrimitive Returns an approximate range based on a fixed number of evaluations
tryTranslateInPlace(dx: number, dy: number = 0.0, dz: number = 0.0): boolean CurvePrimitive try to move the geometry by dx,dy,dz
areAlmostEqual(a: undefined | GeometryQuery, b: undefined | GeometryQuery): boolean Static CurvePrimitive apply instance method isAlmostEqual if both are defined.
installStrokeCountMap(curve: CurvePrimitive, curveMap: StrokeCountMap, parentMap?: StrokeCountMap): void Static CurvePrimitive final install step to save curveMap in curve.

### Properties

Name Type Description
curvePrimitiveType Readonly "lineString" String name for schema properties
fractions Accessor ReadOnly undefined | GrowableFloat64Array 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 undefined | GrowableFloat64Array Return the (optional) array of normal indices.
packedDerivatives Accessor ReadOnly undefined | GrowableXYZArray Return the (optional) array of derivatives.
packedPoints Accessor ReadOnly Return (reference to) point data in packed GrowableXYZArray.
packedSurfaceNormals Accessor ReadOnly undefined | GrowableXYZArray Return the (optional) array of surface normals.
packedUVParams Accessor ReadOnly undefined | GrowableXYArray Return the (optional) array of uv params.
paramIndices Accessor ReadOnly undefined | GrowableFloat64Array Return the (optional) array of param indices.
pointIndices Accessor ReadOnly undefined | GrowableFloat64Array 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 ReadOnly undefined | GeometryQuery[] CurvePrimitive return GeometryQuery children for recursive queries.

* leaf classes do not need to implement.
geometryCategory Readonly "curvePrimitive" CurvePrimitive String name for schema properties
parent undefined | any CurvePrimitive data attached by various algorithms (e.g.
strokeData undefined | StrokeCountMap CurvePrimitive data attached during stroking for facets.

### Defined in

Last Updated: 22 March, 2023