Util

Modules

Enumerations


Type aliases

Action

ActionLike

ActionResult

LazyLike

Functions

TypeAssert

Communicator.Util.TypeAssert(_x)

This purpose of this function is guarantee a value is of a given type.

This is essentially a compile time console.assert(x instanceof T).

This function is useful when terminating a type-narrowing if-else chain in that this function makes the code more robust to future type changes.

Warning:

T=never doesn’t appear to work properly, hence the existence of TypeAssertNever.

Example:

declare const x: Foo | Bar;
if (x instanceof Foo) {
    console.log("foo");
}
else {
    // This becomes a compiler error if, for example, `x`'s type gets changed to add `Baz`:
    //    x: Foo | Bar | Baz
    TypeAssert<Bar>(x);
    console.log("bar");
}
Arguments
  • _x (T()) –

Return type

void

This is essentially a compile time console.assert(x instanceof T).

This function is useful when terminating a type-narrowing if-else chain in that this function makes the code more robust to future type changes.

Warning:

T=never doesn’t appear to work properly, hence the existence of TypeAssertNever.

Example:

declare const x: Foo | Bar;
if (x instanceof Foo) {
    console.log("foo");
}
else {
    // This becomes a compiler error if, for example, `x`'s type gets changed to add `Baz`:
    //    x: Foo | Bar | Baz
    TypeAssert<Bar>(x);
    console.log("bar");
}

TypeAssertNever

Communicator.Util.TypeAssertNever(_x)

See TypeAssert for details.

This is useful for making the compiler enforce fully-covered switch statements.

This function unconditionally throws InternalLogicError.

Example:

switch (x) {
    case Enum.A:
        break;
    case Enum.B:
        break;
    default:
        TypeAssertNever(x); // compiler complains if missing other enum cases
}
Arguments
  • _x (never()) –

Return type

never

This is useful for making the compiler enforce fully-covered switch statements.

This function unconditionally throws InternalLogicError.

Example:

switch (x) {
    case Enum.A:
        break;
    case Enum.B:
        break;
    default:
        TypeAssertNever(x); // compiler complains if missing other enum cases
}

closestPointFromPointToSegment

Communicator.Util.closestPointFromPointToSegment(p0, p1, point)

Finds the closest point on line segment p0-p1 to the given point. The closest point will always lie on or between the line segment endpoints.

Arguments
  • p0 (Point3()) – First point of the line segment

  • p1 (Point3()) – Second point of the line segment

  • point (Point3()) – Point at which to find closest line segment point.

Return type

Point3()

closestPointScalarFromPointToSegment

Communicator.Util.closestPointScalarFromPointToSegment(p0, p1, point)

Finds the scalar for the closest point on line segment p0-p1 to the given point. The returned scalar will always be in the range [0, 1], where 0 indicates p0 is closest, and 1 indicates p1 is closest.

Arguments
  • p0 (Point3()) – First point of the line segment

  • p1 (Point3()) – Second point of the line segment

  • point (Point3()) – Point at which to find closest line segment scalar

Return type

number

computeAngleBetweenVector

Communicator.Util.computeAngleBetweenVector(vector1, vector2)

Computes the smallest angle between two vectors in degrees.

Arguments
  • vector1 (Point3()) – The first vector.

  • vector2 (Point3()) – The second vector.

Return type

Degrees

Returns

The angle between vectors in degrees.

computeOffaxisRotation

Communicator.Util.computeOffaxisRotation(axisVector, degrees[, out_rotationMatrix])

Computes the rotation matrix defined by rotating around a vector.

Arguments
  • axisVector (Point3()) – The vector to rotate around.

  • degrees (Degrees) – The amount to rotate.

  • out_rotationMatrix (Matrix()) – optional The out parameter for the rotation matrix.

Return type

Matrix()

Returns

The out parameter rotation matrix.

computePointToLineDistance

Communicator.Util.computePointToLineDistance(point, lineBegin, lineEnd, out_closestPointOnLine)

Computes the shortest distance between a point and a line segment.

Arguments
  • point (Point3()) –

  • lineBegin (Point3()) – The start point of the line segment to compute against.

  • lineEnd (Point3()) – The end point of the line segment to compute against.

  • out_closestPointOnLine (Point3()) – The out parameter for a closest point on the line segment to the point.

Return type

number

Returns

The distance from the point and the closest point on the line.

copyMap

Communicator.Util.copyMap(input)

Performs a shallow copy of a Map.

Arguments
  • input (Map) – The Map to be copied

Return type

Map <K, V>

copySet

Communicator.Util.copySet(input)

Performs a shallow copy of a Set.

Arguments
  • input (Set) – The Map to be copied

Return type

Set <T>

createCylinderMeshDataFromArc

Communicator.Util.createCylinderMeshDataFromArc(arc, axisDirection, numSegments, scale)

Creates a cylinder that is deformed by an arc. An example of the resulting geometry can be observed in the Handles implementation.

Arguments
  • arc ([number]()) – an array of numbers describing points on an arc that will be used to deform the cylinder

  • axisDirection (Point3()) – cylinder axis.

  • numSegments (number()) – the number of segments to use when constructing the cylinder. A higher number will give a smoother appearance but consume more memory.

  • scale (number()) – a scaling factor to apply to the geometry.

Return type

MeshData()

degreesToRadians

Communicator.Util.degreesToRadians(degrees)

Converts degrees to radians.

Arguments
  • degrees (Degrees) – The degrees to convert.

Return type

Radians

Returns

The converted radians.

delayCall

Communicator.Util.delayCall(cb, args)

This function is an helper function that delay the call to a callback to the computation of the next ‘frame’ of the browser’s js engine. The point is to let the js engine deal with pending promises before running the given code.

Arguments
  • cb (function()) – the callback to call the promise to call on the next frame.

  • args ([any]()) – the arguments of the callback.

Return type

ReturnType <setTimeout>

Returns

a timeout id in order to cancel it if necessary.

Communicator.Util.cb(cbArgs)
Arguments
  • cbArgs ([any]()) –

Return type

any

distanceLineLine

Communicator.Util.distanceLineLine(line1Begin, line1End, line2Begin, line2End, out_closestPointLine1, out_closestPointLine2)

Returns the distance between two line segments.

Arguments
  • line1Begin (Point3()) – The start of the first line segment.

  • line1End (Point3()) – The end of the first line segment.

  • line2Begin (Point3()) – The start of the second line segment.

  • line2End (Point3()) – The end of the second line segment.

  • out_closestPointLine1 (Point3()) – Out parameter for the closest point of line1 to line2.

  • out_closestPointLine2 (Point3()) – Out parameter for the closest point of line2 to line1.

Return type

number

Returns

The distance between the two input line segments.

exchangeIdEqual

Communicator.Util.exchangeIdEqual(exchangeIdA, exchangeIdB)

Check if two exchange ids are equal.

Arguments
  • exchangeIdA (ExchangeId) – the first exchange id to compare.

  • exchangeIdB (ExchangeId) – the second exchange id to compare.

Return type

boolean

Returns

true or false if exchange ids are equal.

filterInPlace

Communicator.Util.filterInPlace(xs, pred)

This function takes an array of type , and a predicate function to test each element of the array. This function does not create a new array.

Arguments
  • xs ([T]()) – Array to filter.

  • pred (function()) – If this function returns true when testing an item, the item will be kept in the array, otherwise the item will be removed.

Return type

void

Communicator.Util.pred(x)
Arguments
  • x (T()) –

Return type

boolean

formatWithUnit

Communicator.Util.formatWithUnit(value, unit)

Returns the formatted string of a value and its units. Unit scaling is based on unit === 1 being for millimeters.

Arguments
  • value (number()) – The value to format (without units).

  • unit (number()) – The unit scale to be applied to value.

Return type

string

generateArcPoints

Communicator.Util.generateArcPoints(axis, angle, center, startOffset, segmentCount)

Returns an array of evenly-distributed points that lie on an arc.

Arguments
  • axis (Point3()) – The normal of the plane containing the arc (in other words, the axis of rotation).

  • angle (number()) – The angle swept by the arc (may be negative).

  • center (Point3()) – The center point of the arc.

  • startOffset (Point3()) – The starting point of the arc, expressed as an offset relative to the center.

  • segmentCount (number()) – The number of line segments to be generated.

Return type

[Point3()]

Returns

An array containing segmentCount + 1 points.

generateConeCylinderMeshData

Communicator.Util.generateConeCylinderMeshData(cylinderRadius, numSegments, stemHeight, coneBaseRadius, capHeight, taperHeight)

Creates a cylinder with an attached cone. An example of the resulting geometry can be observed in the default Axis Triad or Handles implementation.

Arguments
  • cylinderRadius (number()) – the radius of the cylinder portion of the geometry.

  • numSegments (number()) – the number of segments used to create the cylinder and cone portions. Increasing this number will result in a smoother appearance but consume more memory.

  • stemHeight (number()) – the height of the cone portion.

  • coneBaseRadius (number()) – the radius of the cone portion

  • capHeight (number()) – the height of the cylinder cap

  • taperHeight (number()) – the height of the taper.

Return type

MeshData()

generatePointsOnCircle

Communicator.Util.generatePointsOnCircle(out_points, center, radius, numPoints, axisVector)

Generates tessellated points suitable for mesh creation for a given circle.

Arguments
  • out_points ([Point3()]) – The out parameter for the generated points.

  • center (Point3()) – The center of the circle.

  • radius (number()) – The radius of the circle.

  • numPoints (number()) – The number of points to use for the tesesselated circle.

  • axisVector (Point3()) – The axis to orient the circle against.

Return type

void

generateSphereMeshData

Communicator.Util.generateSphereMeshData()

Creates a basic sphere with normals.

Return type

MeshData()

getLongUnitString

Communicator.Util.getLongUnitString(unit)
Arguments
Return type

string

intersect3d2Planes

Communicator.Util.intersect3d2Planes(plane1, pointOnPlane1, plane2, pointOnPlane2, out_lineBegin, out_lineEnd)

Computes the intersection of two planes.

Arguments
  • plane1 (Plane()) – The first plane.

  • pointOnPlane1 (Point3()) – A point on the first plane.

  • plane2 (Plane()) – The second plane.

  • pointOnPlane2 (Point3()) – A point on the second plane.

  • out_lineBegin (Point3()) – Out parameter for resulting intersection line (if any).

  • out_lineEnd (Point3()) – Out parameter for resulting intersection line (if any).

Return type

0 | 1 | 2

Returns

0 if the planes are disjoint. 1 if the planes coincide. 2 if the planes intersect in a line.

intersectionPlaneLine

Communicator.Util.intersectionPlaneLine(lineBegin, lineEnd, planePoint1, planePoint2, planePoint3, out_intersectionPoint)

Computes the intersection of a line segment and a plane.

Arguments
  • lineBegin (Point3()) – The start point of the line segment to intersect.

  • lineEnd (Point3()) – The end point of the line segment to intersect.

  • planePoint1 (Point3()) – A point on the plane to intersect.

  • planePoint2 (Point3()) – A point on the plane to intersect.

  • planePoint3 (Point3()) – A point on the plane to intersect.

  • out_intersectionPoint (Point3()) – The out parameter for the point of intersection if one exists.

Return type

boolean

Returns

True if the line segment and plane intersect. False otherwise.

See also: [[intersectionPlaneLine2]].

intersectionPlaneLine2

Communicator.Util.intersectionPlaneLine2(lineBegin, lineEnd, plane, out_intersectionPoint)

Computes the intersection of a line segment and a plane.

Arguments
  • lineBegin (Point3()) – The start point of the line segment to intersect.

  • lineEnd (Point3()) – The end point of the line segment to intersect.

  • plane (Plane()) – The plane to intersect.

  • out_intersectionPoint (Point3()) – The out parameter for the point of intersection if one exists.

Return type

boolean

Returns

True if the line segment and plane intersect. False otherwise.

isPointInRect2d

Communicator.Util.isPointInRect2d(point, rectPos, rectSize[, tolerance])

Returns whether the 2-dimensional point point lies within the given rectangle.

Arguments
  • point (Point2()) – The point to test

  • rectPos (Point2()) – The lower-left corner of the rectangle

  • rectSize (Point2()) – The width and height of the rectangle

  • tolerance (number()) – optional The maximum distance along the x- or y-axis that point is allowed to be outside the rectangle

Return type

boolean

isPointOnLineSegment

Communicator.Util.isPointOnLineSegment(p0, p1, point, epsilon)

Determine if the point is both on the line formed by p0-p1, and within the p0-p1 line-segment endpoints

Arguments
  • p0 (Point3()) – First point of the line segment

  • p1 (Point3()) – Second point of the line segment

  • point (Point3()) – Point that possibly lies on the line segment.

  • epsilon (number()) – Epsilon value used with point-on-line distance calculation.

Return type

boolean

isPointOnLineSegment2d

Communicator.Util.isPointOnLineSegment2d(point, p1, p2, tolerance)

Returns whether the 2-dimensional point point lies on the line segment p1p2.

Arguments
  • point (Point2()) – The point to test

  • p1 (Point2()) – The first endpoint of the line segment

  • p2 (Point2()) – The second endpoint of the line segment

  • tolerance (number()) – If the perpendicular distance of point from the line segment is less than or equal to tolerance, the function will return true.

Return type

boolean

lineLineIntersect

Communicator.Util.lineLineIntersect(p1, p2, p3, p4)

Returns the closest point on line p1p2 to line p3p4.

Arguments
Return type

Point3() | null

oneVectorCross

Communicator.Util.oneVectorCross(vector[, out_crossVector])

Returns the cross product of a vector against its least significant axis.

Arguments
  • vector (Point3()) – The input vector to cross.

  • out_crossVector (Point3()) – optional The out parameter for the cross product.

Return type

Point3()

radiansToDegrees

Communicator.Util.radiansToDegrees(radians)

Converts radians to degrees.

Arguments
Return type

Degrees

Returns

The converted degrees.

setSubtraction

Communicator.Util.setSubtraction(setA, setB)

Returns a new set consisting of all elements in setA not found in setB.

Arguments
  • setA (Set) – The starting set to start subtracting from.

  • setB (Set) – The set used to reject values from setA.

Return type

Set <T>

Returns

The resulting set.

setToArray

Communicator.Util.setToArray(set)

Turns a Set into an Array.

Arguments
  • set (Set) – The set to convert.

Return type

[T]

Returns

The resulting array.

sleep

Communicator.Util.sleep(duration)

Returns a promise that resolves after the provided number of milliseconds

Arguments
  • duration (Milliseconds) – number of milliseconds until the returned promise can resolve

Return type

Promise <void>

toSet

Communicator.Util.toSet(xs)

Creates a Set from the provided array.

Arguments
  • xs ([T]()) – Array to create a Set from

Return type

Set <T>

waitForAll

Communicator.Util.waitForAll(promises)

This function behaves like writing [[Promise.all(promises).then(no_op)]] but does not incur the overhead of creating a .then promise. Using this function can provide a performance boost when doing large amounts of batch processing with groups of promises.

Arguments
  • promises ([Promise <void>]()) – array of promises.

Return type

Promise <void>