Points in Bitbybit

View Full Source & Details on GitHub

bitbybit.point builds, moves and measures points.

What a point is

A point is an array of three numbers, [x, y, z], with Y pointing up, so the ground is the XZ plane. A vector has the same shape, so a point can be passed where a vector is expected and back. A 2D point is [x, y].

Every function gives new points or numbers and leaves its input unchanged. Angles are in degrees and lengths in model units.

Making points and patterns

• pointXYZ builds [x, y, z], and pointXY builds the 2D point [x, y].
• multiplyPoint repeats one point amountOfPoints times.
• arcThroughThreePoints lays out points along the circular arc from start through middle to end, in segments equal steps (default 16). Three points on one line fix no arc and come back as they are.
• spiral lays out numberPoints points along a logarithmic spiral in the XY plane, from the origin out to radius; phi, widening and factor shape how it opens.
• hexGrid gives the centers of a honeycomb of hexagons in the XY plane, nrHexagonsX columns along X and nrHexagonsY rows along Y, with every second row shifted by half a column. radiusHexagon is the distance from a center to a corner.
• hexGridScaledToFit fills a width by height rectangle with nrHexagonsInWidth by nrHexagonsInHeight hexagons. It gives the centers, the six corners of every hexagon in hexagons, the shortest and longest edge, and the largest fillet radius that fits every corner. A corner points up unless flatTop is on, and the extend... options stretch the outer rows past the edges so the rectangle has no jagged border.

Both hex grids start at the origin unless you center them (orientOnCenter, centerGrid), and pointsOnGround lays them on the XZ ground plane instead.

Moving, rotating and scaling

• translatePoints moves every point by one vector, and translateXYZPoints by separate x, y and z amounts. translatePointsWithVectors moves each point by its own vector.
• rotatePointsCenterAxis turns points by angle degrees around an axis through center, counter-clockwise when the axis points toward you.
• scalePointsCenterXYZ scales points about a center with a factor per axis, so [1, 2, 1] doubles distances along Y only.
• stretchPointsDirFromCenter stretches points along one direction, measured from a center; distances across it stay the same.
• transformPoint and transformPoints apply a transformation matrix, or a list of them in order, such as bitbybit.babylon.transforms builds. transformsForPoints applies a different one to each point.

translatePointsWithVectors and transformsForPoints throw unless both lists have the same length.

Measuring

• getX, getY and getZ read one coordinate.
• distance measures between two points, and distancesToPoints from one point to each point of a list.
• closestPointFromPoints gives the nearest point of a list, and closestPointFromPointsDistance the distance to it. closestPointFromPointsIndex gives its position counted from 1, not 0, so the first point of the list is 1.
• averagePoint gives the average of the points.
• boundingBoxOfPoints gives the smallest axis-aligned box around the points: its min and max corners, center, and width (along X), height (along Y) and length (along Z).
• twoPointsAlmostEqual tells whether two points are closer together than tolerance.
• normalFromThreePoints gives the unit direction at right angles to the plane through three points, by the right-hand rule from the first point to the second to the third; reverseNormal flips it. Points on one line give undefined.

Fillets at corners

These find the largest radius a rounded corner can have, which is useful before filleting a polyline or a wire.

• maxFilletRadius takes one corner. Note the names: end is the corner itself, and start and center are the far ends of the two segments that meet there. The radius is limited by the shorter segment.
• maxFilletRadiusHalfLine limits the arc to the nearer half of each segment, so neighbouring corners of a polyline can all be filleted without their arcs overlapping.
• maxFilletsHalfLine gives that radius for every corner of a polyline. With checkLastWithFirst on, the polyline counts as closed and the radii of the corners at its first and last points are added at the end of the list.
• safestPointsMaxFilletHalfLine gives the smallest of those radii: one radius that fits every corner.

A straight or folded-back corner, or a segment shorter than tolerance, allows no fillet and gives 0.

Cleaning and sorting

• removeConsecutiveDuplicates removes a point that repeats the one right before it, within tolerance. With checkFirstAndLast on, a last point that repeats the first is dropped too.
• sortPoints sorts by X, then by Y, then by Z.

Every function

Function	What it does
arcThroughThreePoints	Lays out points along the circular arc through three points, from the first through the second to the third.
averagePoint	Finds the average of the points, which is their center of mass when they weigh the same.
boundingBoxOfPoints	Finds the smallest axis-aligned box that holds all the points.
closestPointFromPoints	Finds the nearest point in a list to a given point.
closestPointFromPointsDistance	Measures the distance from a point to the nearest point in a list.
closestPointFromPointsIndex	Finds the position of the nearest point in a list, counted from 1.
distance	Measures the straight-line distance between two points.
distancesToPoints	Measures the distance from one point to each point in a list.
getX	Reads the X value of a point.
getY	Reads the Y value of a point, the one that points up.
getZ	Reads the Z value of a point.
hexGrid	Lays out the centers of a honeycomb of hexagons in the XY plane.
hexGridScaledToFit	Lays out a honeycomb of hexagons that fills a given width and height, sizing the hexagons from the counts.
maxFilletRadius	Finds the largest fillet that fits a corner: the arc touches both segments and stays inside them.
maxFilletRadiusHalfLine	Finds the largest fillet at a corner whose arc touches each segment within its nearer half, so neighboring corners of a polyline can each be filleted without the arcs overlapping.
maxFilletsHalfLine	Finds the largest fillet for every corner of a polyline, each limited to the nearer half of its segments so the fillets never overlap.
multiplyPoint	Repeats one point a given number of times in a list.
normalFromThreePoints	Finds the direction at right angles to the plane through three points, with length 1.
pointXY	Builds a 2D point from its x and y values.
pointXYZ	Builds a 3D point from its x, y and z values.
removeConsecutiveDuplicates	Removes a point when it repeats the one right before it; the same point further away is kept.
rotatePointsCenterAxis	Rotates points around an axis that passes through a center.
safestPointsMaxFilletHalfLine	Finds one fillet radius that fits every corner of a polyline: the smallest of the per-corner maximums under the half-segment rule.
scalePointsCenterXYZ	Scales points away from or toward a center, with its own factor per axis.
sortPoints	Sorts points by X, then by Y for equal X, then by Z.
spiral	Lays out points along a logarithmic spiral in the XY plane, from the origin outward to radius.
stretchPointsDirFromCenter	Stretches points along one direction, measured from a center; distances across that direction stay as they are.
transformPoint	Applies a transformation matrix, or a list of them in order, to one point.
transformPoints	Applies the same transformation matrix, or list of them in order, to every point.
transformsForPoints	Applies a different transformation to each point: the first transformation to the first point, and so on.
translatePoints	Moves every point by the same vector.
translatePointsWithVectors	Moves each point by its own vector: the first point by the first vector, and so on.
translateXYZPoints	Moves every point by the given x, y and z amounts.
twoPointsAlmostEqual	Tells whether two points are closer together than a tolerance.