Class Frame

Frames: a frame is a point with three axes at right angles, written as its origin, its normal (the Z axis) and its direction (the X axis), the Y axis following from those two. Frames place things: a shape lands on one, points convert between one and the world, and frame patterns lay out copies. Every method returns new values and never changes its inputs.

Index

Constructors

constructor

new Frame(
    vector: Bit.Vector,
    math: MathBitByBit,
    geometryHelper: GeometryHelper,
): Bit.Frame
Parameters
- vector: Bit.Vector
- math: MathBitByBit
- geometryHelper: GeometryHelper
Returns Bit.Frame
- Defined in bitbybit-docs.d.ts:59602

change

translate

translate(inputs: Bit.Inputs.Frame.TranslateDto): Bit.Inputs.Base.Frame
Moves a frame by a vector in world coordinates, keeping the directions of its axes.
Parameters
- inputs: Bit.Inputs.Frame.TranslateDto
  The frame and the vector to move it by
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const moved = bitbybit.frame.translate({ frame: bitbybit.frame.world(), translation: [2, 0, 1] });
```
- Defined in bitbybit-docs.d.ts:59777

translateFrames

translateFrames(inputs: TranslateFramesDto): Bit.Inputs.Base.Frame[]
Moves frames by one vector in world coordinates, as translate moves one; their axes keep their directions.
Parameters
- inputs: TranslateFramesDto
  The frames and the vector to move them by
Returns Bit.Inputs.Base.Frame[]
New frames, in the same order
Example
```
const floor = bitbybit.frame.grid({ countX: 3, countY: 3, spacingX: 2, spacingY: 2, centered: true });
const ceiling = bitbybit.frame.translateFrames({ frames: floor, translation: [0, 0, 3] });
```
- Defined in bitbybit-docs.d.ts:59792

offset

offset(inputs: Bit.Inputs.Frame.OffsetDto): Bit.Inputs.Base.Frame
Moves a frame along its own normal, keeping the directions of its axes.

A negative distance moves it against the normal.
Parameters
- inputs: Bit.Inputs.Frame.OffsetDto
  The frame and the distance in model units
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const lid = bitbybit.frame.offset({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), distance: 10 });
```
- Defined in bitbybit-docs.d.ts:59807

offsetFrames

offsetFrames(inputs: OffsetFramesDto): Bit.Inputs.Base.Frame[]
Moves each frame along its own normal by the same distance, as offset moves one; their axes keep their directions.

Frames facing different ways move different ways: a negative distance moves each against its own normal.
Parameters
- inputs: OffsetFramesDto
  The frames and the distance in model units
Returns Bit.Inputs.Base.Frame[]
New frames, in the same order
Example
```
const ring = bitbybit.frame.polar({ count: 8, radius: 5, angle: 360, startAngle: 0, rotate: true });
const raised = bitbybit.frame.offsetFrames({ frames: ring, distance: 2 });
```
- Defined in bitbybit-docs.d.ts:59825

rotate

rotate(inputs: Bit.Inputs.Frame.RotateDto): Bit.Inputs.Base.Frame
Turns a frame about one of its own axes, through its origin.

The angle is in degrees; positive is counter-clockwise when that axis points toward you.
Parameters
- inputs: Bit.Inputs.Frame.RotateDto
  The frame, the axis to turn about and the angle
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const tilted = bitbybit.frame.rotate({ frame: bitbybit.frame.world(), axis: Bit.Inputs.Frame.frameAxisEnum.x, angle: 30 });
```
- Defined in bitbybit-docs.d.ts:59840

rotateFrames

rotateFrames(inputs: RotateFramesDto): Bit.Inputs.Base.Frame[]
Turns each frame about one of its own axes, through its own origin, as rotate turns one.

The angle is in degrees; positive is counter-clockwise when that axis points toward you.
Parameters
- inputs: RotateFramesDto
  The frames, the axis to turn each about and the angle
Returns Bit.Inputs.Base.Frame[]
New frames, in the same order
Example
```
const row = bitbybit.frame.grid({ countX: 4, countY: 1, spacingX: 2, spacingY: 2, centered: true });
const tilted = bitbybit.frame.rotateFrames({ frames: row, axis: Bit.Inputs.Frame.frameAxisEnum.x, angle: 30 });
```
- Defined in bitbybit-docs.d.ts:59856

flip

flip(inputs: FrameDto): Bit.Inputs.Base.Frame
Turns a frame over: its normal points the other way and its Y axis with it, its origin and X axis stay.
Parameters
- inputs: FrameDto
  The frame to turn over
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const underside = bitbybit.frame.flip({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }) });
```
- Defined in bitbybit-docs.d.ts:59870

flipFrames

flipFrames(inputs: FramesDto): Bit.Inputs.Base.Frame[]
Turns each frame over, as flip turns one: its normal and Y axis point the other way, its origin and X axis stay.
Parameters
- inputs: FramesDto
  The frames to turn over
Returns Bit.Inputs.Base.Frame[]
New frames, in the same order
Example
```
const tops = bitbybit.frame.grid({ countX: 2, countY: 2, spacingX: 3, spacingY: 3, centered: true });
const bottoms = bitbybit.frame.flipFrames({ frames: tops });
```
- Defined in bitbybit-docs.d.ts:59885

coordinates

pointToWorld

pointToWorld(inputs: FramePointDto): Point3
Converts a point given in a frame's coordinates into world coordinates.

[1, 2, 3] becomes the point 1 along the frame's X axis, 2 along its Y axis and 3 along its normal, from its origin.
Parameters
- inputs: FramePointDto
  The frame and the point in its coordinates
Returns Point3
The point in world coordinates
Example
```
const corner = bitbybit.frame.pointToWorld({ frame: bitbybit.frame.zx({ origin: [0, 2, 0] }), point: [1, 1, 0] });
```
- Defined in bitbybit-docs.d.ts:59967

pointToLocal

pointToLocal(inputs: FramePointDto): Point3
Converts a point given in world coordinates into a frame's coordinates, the reverse of pointToWorld.

The third coordinate of the result is the point's signed distance from the frame's plane.
Parameters
- inputs: FramePointDto
  The frame and the point in world coordinates
Returns Point3
The point in the frame's coordinates
Example
```
const local = bitbybit.frame.pointToLocal({ frame: bitbybit.frame.zx({ origin: [0, 2, 0] }), point: [1, 5, 1] });
```
- Defined in bitbybit-docs.d.ts:59983

pointsToWorld

pointsToWorld(inputs: FramePointsDto): Point3[]
Converts points given in a frame's coordinates into world coordinates, as pointToWorld does for one.
Parameters
- inputs: FramePointsDto
  The frame and the points in its coordinates
Returns Point3[]
The points in world coordinates, in the same order
Example
```
const square = bitbybit.frame.pointsToWorld({ frame: bitbybit.frame.yz({ origin: [3, 0, 0] }), points: [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]] });
```
- Defined in bitbybit-docs.d.ts:59997

pointsToLocal

pointsToLocal(inputs: FramePointsDto): Point3[]
Converts points given in world coordinates into a frame's coordinates, as pointToLocal does for one.
Parameters
- inputs: FramePointsDto
  The frame and the points in world coordinates
Returns Point3[]
The points in the frame's coordinates, in the same order
Example
```
const flat = bitbybit.frame.pointsToLocal({ frame: bitbybit.frame.yz({ origin: [3, 0, 0] }), points: [[3, 0, 0], [3, 1, 0], [3, 1, 1]] });
```
- Defined in bitbybit-docs.d.ts:60011

vectorToWorld

vectorToWorld(inputs: FrameVectorDto): Vector3
Turns a vector given along a frame's axes into one along the world axes; the frame's origin plays no part.
Parameters
- inputs: FrameVectorDto
  The frame and the vector along its axes
Returns Vector3
The vector along the world axes
Example
```
const up = bitbybit.frame.vectorToWorld({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), vector: [0, 0, 1] });
```
- Defined in bitbybit-docs.d.ts:60025

vectorToLocal

vectorToLocal(inputs: FrameVectorDto): Vector3
Turns a vector given along the world axes into one along a frame's axes, the reverse of vectorToWorld.
Parameters
- inputs: FrameVectorDto
  The frame and the vector along the world axes
Returns Vector3
The vector along the frame's axes
Example
```
const local = bitbybit.frame.vectorToLocal({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), vector: [0, 1, 0] });
```
- Defined in bitbybit-docs.d.ts:60039

create

create(inputs: CreateFrameDto): Bit.Inputs.Base.Frame
Builds a frame from where it sits, where its Z axis points and roughly where its X axis points.

direction is turned square to normal and both are scaled to length 1, so they only have to be roughly right. A normal of zero length or a direction along it throws.
Parameters
- inputs: CreateFrameDto
  The origin, the normal and the rough X direction
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const tilted = bitbybit.frame.create({ origin: [0, 5, 0], normal: [0, 1, 1], direction: [1, 0, 0] });
```
- Defined in bitbybit-docs.d.ts:59619

world

world(): Bit.Inputs.Base.Frame
Gives the world frame: its origin at zero, its X, Y and Z axes along the world's.

Placing something on the world frame leaves it where it is, and it is the frame the other methods use when one is left out.

Returns Bit.Inputs.Base.Frame
The world frame
Example
```
const world = bitbybit.frame.world();
const raised = bitbybit.frame.offset({ frame: world, distance: 5 });
```
- Defined in bitbybit-docs.d.ts:59635

xy

xy(inputs: OriginDto): Bit.Inputs.Base.Frame
Builds a frame lying in the XY plane: its X axis along the world X, its Y axis along the world Y and its normal along the world Z.
Parameters
- inputs: OriginDto
  Where the frame sits
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const floor = bitbybit.frame.xy({ origin: [0, 0, 2] });
```
- Defined in bitbybit-docs.d.ts:59649

yz

yz(inputs: OriginDto): Bit.Inputs.Base.Frame
Builds a frame lying in the YZ plane: its X axis along the world Y, its Y axis along the world Z and its normal along the world X.
Parameters
- inputs: OriginDto
  Where the frame sits
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const side = bitbybit.frame.yz({ origin: [3, 0, 0] });
```
- Defined in bitbybit-docs.d.ts:59663

zx

zx(inputs: OriginDto): Bit.Inputs.Base.Frame
Builds a frame lying in the ZX plane, the ground when Y points up: its X axis along the world Z, its Y axis along the world X and its normal along the world Y.
Parameters
- inputs: OriginDto
  Where the frame sits
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const ground = bitbybit.frame.zx({ origin: [0, 0, 0] });
```
- Defined in bitbybit-docs.d.ts:59677

fromThreePoints

fromThreePoints(inputs: ThreePointsDto): Bit.Inputs.Base.Frame
Builds a frame from three points: where it sits, a point its X axis runs toward and a point on the side its Y axis points to.

The normal follows by the right-hand rule. xPoint at origin, or three points on one line, throws.
Parameters
- inputs: ThreePointsDto
  The origin, a point along the X axis and a point in the plane
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const frame = bitbybit.frame.fromThreePoints({ origin: [0, 0, 0], xPoint: [4, 0, 0], planePoint: [0, 0, -3] });
```
- Defined in bitbybit-docs.d.ts:59694

fromPointAndNormal

fromPointAndNormal(inputs: PointAndNormalDto): Bit.Inputs.Base.Frame
Builds a frame from a point and a normal, choosing its X axis by a fixed rule.

The same normal always gives the same X axis: square to the normal and to the world axis the normal leans on least. A normal of zero length throws.
Parameters
- inputs: PointAndNormalDto
  The origin and the normal
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const onSlope = bitbybit.frame.fromPointAndNormal({ origin: [2, 1, 0], normal: [0, 1, 1] });
```
- Defined in bitbybit-docs.d.ts:59710

bestFit

bestFit(inputs: BestFitDto): Bit.Inputs.Base.Frame
Fits a frame to points that lie on or near one plane.

It sits at their average. The normal follows their order by the right-hand rule, and X runs along their widest spread, toward the first point; with no widest spread, as around a square, X points at the first point. Fewer than three points, or nearly collinear ones, throw.
Parameters
- inputs: BestFitDto
  The points to fit
Returns Bit.Inputs.Base.Frame
A new frame in the plane that fits the points best
Example
```
const frame = bitbybit.frame.bestFit({ points: [[0, 0, 0], [4, 0.1, 0], [4, 3, 0.1], [0, 3, 0]] });
```
- Defined in bitbybit-docs.d.ts:59727

frame in frame

frameToWorld

frameToWorld(inputs: ChildFrameDto): Bit.Inputs.Base.Frame
Places a frame given in another frame's coordinates into the world: a frame within a frame.

child is read as if parent were the world, so a child at the origin sits on parent and one lifted along Z rises along the parent's normal.
Parameters
- inputs: ChildFrameDto
  The parent frame and the child frame given in its coordinates
Returns Bit.Inputs.Base.Frame
The child frame in world coordinates
Example
```
const table = bitbybit.frame.zx({ origin: [0, 1, 0] });
const onTable = bitbybit.frame.frameToWorld({ parent: table, child: bitbybit.frame.xy({ origin: [0.5, 0.2, 0] }) });
```
- Defined in bitbybit-docs.d.ts:59902

framesToWorld

framesToWorld(inputs: ChildFramesDto): Bit.Inputs.Base.Frame[]
Places frames given in one parent frame's coordinates into the world, as frameToWorld places one: every child sits on parent as it would sit on the world.
Parameters
- inputs: ChildFramesDto
  The parent frame and the frames given in its coordinates
Returns Bit.Inputs.Base.Frame[]
The frames in world coordinates, in the same order
Example
```
const table = bitbybit.frame.zx({ origin: [0, 1, 0] });
const spots = bitbybit.frame.grid({ countX: 3, countY: 2, spacingX: 0.4, spacingY: 0.4, centered: true });
const onTable = bitbybit.frame.framesToWorld({ parent: table, children: spots });
```
- Defined in bitbybit-docs.d.ts:59918

frameToLocal

frameToLocal(inputs: ChildFrameDto): Bit.Inputs.Base.Frame
Describes a frame given in world coordinates in another frame's coordinates, the reverse of frameToWorld.

The result is where child sits and how it turns as seen from parent, as if parent were the world.
Parameters
- inputs: ChildFrameDto
  The parent frame and the child frame in world coordinates
Returns Bit.Inputs.Base.Frame
The child frame in the parent's coordinates
Example
```
const table = bitbybit.frame.zx({ origin: [0, 1, 0] });
const seenFromTable = bitbybit.frame.frameToLocal({ parent: table, child: bitbybit.frame.world() });
```
- Defined in bitbybit-docs.d.ts:59936

framesToLocal

framesToLocal(inputs: ChildFramesDto): Bit.Inputs.Base.Frame[]
Describes frames given in world coordinates in one parent frame's coordinates, the reverse of framesToWorld, as frameToLocal describes one.
Parameters
- inputs: ChildFramesDto
  The parent frame and the frames in world coordinates
Returns Bit.Inputs.Base.Frame[]
The frames in the parent's coordinates, in the same order
Example
```
const table = bitbybit.frame.zx({ origin: [0, 1, 0] });
const seen = bitbybit.frame.framesToLocal({ parent: table, children: [bitbybit.frame.world(), bitbybit.frame.yz({ origin: [2, 0, 0] })] });
```
- Defined in bitbybit-docs.d.ts:59951

matrices

toMatrix

toMatrix(inputs: FrameDto): TransformMatrixes
Gives the transformation that moves anything from the world frame onto a frame.

It takes the world origin to the frame's origin and the world axes to the frame's axes, and comes as a list holding one matrix, the form every transformation input takes.
Parameters
- inputs: FrameDto
  The frame
Returns TransformMatrixes
The transformation onto the frame
Example
```
const onFrame = bitbybit.frame.toMatrix({ frame: bitbybit.frame.zx({ origin: [0, 2, 0] }) });
const moved = bitbybit.point.transformPoints({ points: [[1, 0, 0]], transformation: onFrame });
```
- Defined in bitbybit-docs.d.ts:60056

fromMatrix

fromMatrix(inputs: TransformationDto): Bit.Inputs.Base.Frame
Reads the frame a transformation puts the world frame on: where it moves the world origin and where it turns the world X and Z axes.

Scaling is dropped, a shear keeps the Z axis and squares X to it, and a mirror keeps X and Z with the Y axis that follows from them. A perspective part throws.
Parameters
- inputs: TransformationDto
  The transformation
Returns Bit.Inputs.Base.Frame
A new frame
Example
```
const turned = bitbybit.transforms.rotationCenterAxis({ center: [0, 0, 0], axis: [0, 1, 0], angle: 45 });
const frame = bitbybit.frame.fromMatrix({ transformation: turned });
```
- Defined in bitbybit-docs.d.ts:60074

matrixFromTo

matrixFromTo(inputs: Bit.Inputs.Frame.FromToDto): TransformMatrixes
Gives the transformation that carries anything placed on one frame onto another, turning it the same way.

Left out, from is the world frame, which makes this toMatrix of to. The result is a list holding one matrix.
Parameters
- inputs: Bit.Inputs.Frame.FromToDto
  The frame to move onto and the frame to move from
Returns TransformMatrixes
The transformation from from onto to
Example
```
const from = bitbybit.frame.xy({ origin: [0, 0, 0] });
const to = bitbybit.frame.zx({ origin: [0, 3, 0] });
const carry = bitbybit.frame.matrixFromTo({ to, from });
```
- Defined in bitbybit-docs.d.ts:60093

patterns

grid

grid(inputs: GridDto): Bit.Inputs.Base.Frame[]
Lays out a rectangular grid of frames in a frame's plane, each turned the same way as that frame.

The frames come row by row, along X first. Left out, frame is the world frame, so the grid lies in the XY plane.
Parameters
- inputs: GridDto
  The frame to follow, the counts and spacings, and whether to center the grid
Returns Bit.Inputs.Base.Frame[]
The frames of the grid
Example
```
const spots = bitbybit.frame.grid({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), countX: 4, countY: 3, spacingX: 2, spacingY: 2, centered: true });
```
- Defined in bitbybit-docs.d.ts:60110

polar

polar(inputs: PolarDto): Bit.Inputs.Base.Frame[]
Lays out a ring of frames around a frame's normal, in its plane.

Each is frame turned by its angle about the normal and moved out by radius along its turned X axis. A full turn spaces them evenly, a smaller angle puts one at each end, and a larger one throws. Left out, frame is the world frame.
Parameters
- inputs: PolarDto
  The frame to turn around, the count, radius, angles and whether frames turn
Returns Bit.Inputs.Base.Frame[]
The frames of the ring, in the direction of the angle
Example
```
const bolts = bitbybit.frame.polar({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), count: 8, radius: 5, angle: 360, startAngle: 0, rotate: true });
```
- Defined in bitbybit-docs.d.ts:60127

hexGrid

hexGrid(inputs: HexGridDto): Bit.Inputs.Base.Frame[]
Lays out a honeycomb of frames in a frame's plane, one at each hexagon's center, turned as that frame is.

The hexagons have corners toward the frame's Y axis and flat sides toward X. Rows run along X, every second shifted by half a hexagon, and frames come row by row. Left out, frame is the world frame.
Parameters
- inputs: HexGridDto
  The frame to follow, the counts, the hexagon size and whether to center it
Returns Bit.Inputs.Base.Frame[]
The frames of the honeycomb
Example
```
const cells = bitbybit.frame.hexGrid({ frame: bitbybit.frame.zx({ origin: [0, 0, 0] }), countX: 5, countY: 4, radius: 1, centered: true });
```
- Defined in bitbybit-docs.d.ts:60145

read

origin

origin(inputs: FrameDto): Point3
Reads where a frame sits: the point its three axes start from.
Parameters
- inputs: FrameDto
  The frame to read
Returns Point3
The origin
- Defined in bitbybit-docs.d.ts:59736

normal

normal(inputs: FrameDto): Vector3
Reads where a frame's Z axis points, as a vector of length 1.
Parameters
- inputs: FrameDto
  The frame to read
Returns Vector3
The normal
- Defined in bitbybit-docs.d.ts:59745

direction

direction(inputs: FrameDto): Vector3
Reads where a frame's X axis points, as a vector of length 1 square to the normal.
Parameters
- inputs: FrameDto
  The frame to read
Returns Vector3
The X direction
- Defined in bitbybit-docs.d.ts:59754

yDirection

yDirection(inputs: FrameDto): Vector3
Reads where a frame's Y axis points: the normal crossed with the direction, as a vector of length 1.
Parameters
- inputs: FrameDto
  The frame to read
Returns Vector3
The Y direction
- Defined in bitbybit-docs.d.ts:59764

Class Frame

Index

Constructors

change

coordinates

create

frame in frame

matrices

patterns

read

Constructors

constructor

Parameters

Returns Bit.Frame

change

translate

Parameters

Returns Bit.Inputs.Base.Frame

Example

translateFrames

Parameters

Returns Bit.Inputs.Base.Frame[]

Example

offset

Parameters

Returns Bit.Inputs.Base.Frame

Example

offsetFrames

Parameters

Returns Bit.Inputs.Base.Frame[]

Example

rotate

Parameters

Returns Bit.Inputs.Base.Frame

Example

rotateFrames

Parameters

Returns Bit.Inputs.Base.Frame[]

Example

flip

Parameters

Returns Bit.Inputs.Base.Frame

Example

flipFrames

Parameters

Returns Bit.Inputs.Base.Frame[]

Example

coordinates

pointToWorld

Parameters

Returns Point3

Example

pointToLocal

Parameters

Returns Point3

Example

pointsToWorld

Parameters

Returns Point3[]

Example

pointsToLocal

Parameters

Returns Point3[]

Example

vectorToWorld

Parameters

Returns Vector3

Example

vectorToLocal

Parameters

Returns Vector3

Example

create

create

Parameters

Returns Bit.Inputs.Base.Frame

Example

world

Returns Bit.Inputs.Base.Frame

Example