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.  
addPointXYZ(x: number, y: number, z: number = 0): void Add a point to the linestring.  
addPoints(...points: any[]): void Add points 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: Readonly<WritableXAndY>): 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  
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(): 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, 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): 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(): Point3d evaluate the end point of the linestring.  
ensureEmptyDerivatives(): GrowableXYZArray Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.  
ensureEmptyFractions(): GrowableFloat64Array Ensure that the fraction array exists with no fractions but at least the capacity of the point array.  
ensureEmptyNormalIndices(): GrowableFloat64Array Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.  
ensureEmptyPointIndices(): GrowableFloat64Array Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.  
ensureEmptySurfaceNormals(): GrowableXYZArray Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.  
ensureEmptyUVIndices(): GrowableFloat64Array Ensure that the surfaceNormals array exists with no points but at least the capacity of the point array.  
ensureEmptyUVParams(): GrowableXYArray 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): 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): 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(plane: Plane3dByOriginAndUnitNormal): 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): 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: Ray3d | Vector3d, 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): 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 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(): Point3d 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[]): 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: undefined | 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.  

Inherited methods

Name Inherited from Description
collectCurvePrimitives(collectorArray?: CurvePrimitive[], smallestPossiblePrimitives: boolean = false, explodeLinestrings: boolean = false): CurvePrimitive[] 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): Point3d 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): 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): CurveLocationDetail Protected CurvePrimitive Generic algorithm to search for point at signed distance from a fractional startPoint.
range(transform?: Transform, result?: Range3d): Range3d CurvePrimitive return the range of the entire (tree) GeometryQuery
rangeBetweenFractionsByClone(fraction0: number, fraction1: number, transform?: Transform): Range3d 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): Range3d 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 GrowableXYZArray 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: 20 June, 2023