class Geometry · Computations

Pins

Computations on pins: moving, turning and scaling them, placing them on or beside shapes, and reading their position, direction and length.

Pins replace angle math. A point at angle a and distance r from a center: take a reference pin at the center, turn it with Pins.rotateBy(ref, a) and move it with Pins.moveForward(pin, r); no sine or cosine needed. Positive angles turn clockwise on screen (Pins.angle is the exception: it measures counterclockwise). moveForward moves by the given distance, whatever the length of the pin's direction. Something that turns as a whole (a clock hand, a dial) is simpler as a layer whose anchor is turned with Pins.rotateBy, its content built once around (0, 0).

Static methods

alignToSegmentstatic

static alignToSegment(pin: Pin | PinLike, p1: Point | VectorLike, p2: Point | VectorLike, result?: Pin | null): Pin

Aligns the pin's orientation with the direction from p1 to p2, preserving the orientation's current length. The pin's location is unaffected. If p1 and p2 coincide, the orientation is left unchanged.

pin
The pin whose orientation to align.
p1
The starting point defining the direction.
p2
The ending point defining the direction.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin whose orientation points from p1 toward p2.

anglestatic

static angle(pin: Pin | PinLike, result?: Real | null): Real

Calculates the angle of the pin's orientation relative to the positive X-axis, measured counter-clockwise on screen (like Vectors.Angle(direction, clockwise: false)).

This is the opposite sense of rotateBy: rotating a pin by a gives an angle of 2π - a.

pin
The pin whose orientation angle to calculate.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The angle of the pin's orientation, in radians, in the range [0, 2π).

copystatic

static copy(pin: Pin | PinLike, result?: Pin | null): Pin

Creates a copy of the specified pin with the same location and orientation.

pin
The pin to copy.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A copy of pin.

distanceTostatic

static distanceTo(pin: Pin | PinLike, point: Point | VectorLike, result?: Real | null): Real

Computes the distance from the pin's location to a given point.

pin
The pin whose location is used as the reference.
point
The point to measure the distance to.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The distance between the pin's location and point.

flipXstatic

static flipX(pin: Pin | PinLike, result?: Pin | null): Pin

Flips the pin by inverting only its X orientation component. This mirrors the pin horizontally while preserving its Y orientation.

pin
The pin to flip.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with inverted orientation in the X direction.

flipYstatic

static flipY(pin: Pin | PinLike, result?: Pin | null): Pin

Flips the pin by inverting only its Y orientation component. This mirrors the pin vertically while preserving its X orientation.

pin
The pin to flip.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with inverted orientation in the Y direction.

fromSegmentstatic

static fromSegment(p1: Point | VectorLike, p2: Point | VectorLike, result?: Pin | null): Pin

Creates a pin at p1 that points to p2; its length is the distance between them, so Pins.tip of the result is p2.

E.g. a pin from two handles, for shapes that take a pin: Polygons.regular(Pins.fromSegment(center, handle), 6). Two equal points give a pin of length 0 (no direction).

p1
The position of the pin.
p2
The point the pin points to.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns The pin from p1 to p2.

getOrientationstatic

static getOrientation(pin: Pin | PinLike, result?: Vector | null): Vector

Gets the orientation of the specified pin as a direction vector.

pin
The pin whose orientation to retrieve.
result optional
Optional Vector to write the result into; it is returned. Without it, a new Vector is returned.

Returns The pin's orientation.

getPositionstatic

static getPosition(pin: Pin | PinLike, result?: Point | null): Point

Returns the pin's location as a standalone point.

pin
The pin whose location to retrieve.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The pin's current location.

interpolatestatic

static interpolate(a: Pin | PinLike, b: Pin | PinLike, t: Real | NumberLike, result?: Pin | null): Pin

Linearly interpolates between two pins by the specified factor. Both location and orientation are interpolated independently.

a
The starting pin, corresponding to t = 0.
b
The ending pin, corresponding to t = 1.
t
The interpolation factor. 0 returns a, 1 returns b.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin interpolated between a and b at the specified factor.

lenstatic

static len(pin: Pin | PinLike, result?: Real | null): Real

Gets the length (magnitude) of the pin's orientation vector.

pin
The pin whose orientation length to measure.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The length of the pin's orientation vector.

lookAtstatic

static lookAt(pin: Pin | PinLike, target: Point | VectorLike, result?: Pin | null): Pin

Orients the pin toward a target point, preserving the orientation's current length. The pin's location is unaffected. If the target coincides with the pin's location, the orientation is left unchanged.

pin
The pin to orient.
target
The point to orient toward.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin whose orientation points from its location toward target.

moveBackwardstatic

static moveBackward(pin: Pin | PinLike, length: Real | NumberLike, result?: Pin | null): Pin

Moves the pin backward along its current orientation by the specified length. The backward direction is opposite to the pin's forward orientation.

pin
The pin to move.
length
The distance to move backward.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin moved backward by the specified length.

moveBystatic

static moveBy(pin: Pin | PinLike, direction: Vector | VectorLike, result?: Pin | null): Pin

Translates the pin's location by an arbitrary direction vector. The pin's orientation is unaffected.

pin
The pin to move.
direction
The direction vector by which to move the pin's location.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin whose location has been shifted by direction.

moveForwardstatic

static moveForward(pin: Pin | PinLike, length: Real | NumberLike, result?: Pin | null): Pin

Moves the pin forward along its current orientation by the specified length. The forward direction is determined by the pin's current orientation.

pin
The pin to move.
length
The distance to move forward.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin moved forward by the specified length.

moveLeftstatic

static moveLeft(pin: Pin | PinLike, length: Real | NumberLike, result?: Pin | null): Pin

Moves the pin left relative to its current orientation by the specified length. The left direction is perpendicular to the pin's forward orientation.

pin
The pin to move.
length
The distance to move to the left.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin moved left by the specified length.

moveRightstatic

static moveRight(pin: Pin | PinLike, length: Real | NumberLike, result?: Pin | null): Pin

Moves the pin right relative to its current orientation by the specified length. The right direction is perpendicular to the pin's forward orientation.

pin
The pin to move.
length
The distance to move to the right.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin moved right by the specified length.

placeAndAlignBesideSegmentstatic

static placeAndAlignBesideSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, distance: Real | NumberLike, left: Bool | BoolLike, result?: Pin | null): Pin

Places a pin beside a line segment at the specified ratio, offset perpendicular to the segment by the specified distance, and aligns its orientation with the direction from p1 to p2. The pin is offset to the left or right of the segment direction depending on left. The orientation's current length is preserved. If p1 and p2 coincide, the pin is placed at p1 with its orientation unchanged.

p1
The starting point of the segment.
p2
The ending point of the segment.
ratio
The position along the segment (0 to 1).
distance
The perpendicular distance to offset from the segment.
left
If true, the pin is offset to the left of the segment direction; if false, to the right.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned beside the segment at the specified ratio and perpendicular offset, oriented along the segment direction.

placeAndAlignOnArcstatic

static placeAndAlignOnArc(center: Point | VectorLike, radius: Real | NumberLike, startDir: Vector | VectorLike, endDir: Vector | VectorLike, ratio: Real | NumberLike, clockwise: Bool | BoolLike, result?: Pin | null): Pin

Places a pin on an arc at the specified ratio and aligns its orientation tangentially to the arc at that position. A ratio of 0 corresponds to the start direction, 1 to the end direction. The orientation's current length is preserved.

center
The center point of the arc.
radius
The radius of the arc.
startDir
The direction from the center to the start of the arc.
endDir
The direction from the center to the end of the arc.
ratio
The position along the arc (0 to 1).
clockwise
The direction from startDir to endDir: clockwise in the mathematical sense (y axis up), so true runs counterclockwise on the screen: the other way than Arcs.arcBetween and Vectors.angle. For example, from the direction (1, 0) to (-1, 0) true passes the top of the circle. To keep one convention, build the arc with Arcs.arcBetween and use Arcs.pointAt, Arcs.pinAt or Arcs.closestPoint.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the arc at the specified ratio with its orientation tangent to the arc.

placeAndAlignOnCirclestatic

static placeAndAlignOnCircle(center: Point | VectorLike, radius: Real | NumberLike, angle: Real | NumberLike, result?: Pin | null): Pin

Places a pin on a circle at the specified angle and aligns its orientation tangentially to the circle. The orientation's current length is preserved.

center
The center point of the circle.
radius
The radius of the circle.
angle
The angle at which to place the pin on the circle.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the circle at the specified angle with its orientation tangent to the circle.

placeAndAlignOnSegmentstatic

static placeAndAlignOnSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, result?: Pin | null): Pin

Places a pin on a line segment at the specified ratio and aligns its orientation with the direction from p1 to p2. A ratio of 0 places the pin at p1, 1 at p2, and 0.5 at the midpoint. The orientation's current length is preserved. If p1 and p2 coincide, the orientation is left unchanged.

p1
The starting point of the segment.
p2
The ending point of the segment.
ratio
The position along the segment (0 to 1).
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the segment at the specified ratio with its orientation aligned to the segment.

placeAtstatic

static placeAt(pin: Pin | PinLike, point: Point | VectorLike, result?: Pin | null): Pin

Places the pin at the specified point, preserving its current orientation.

pin
The pin to place.
point
The point at which to place the pin.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned at point.

placeBesideSegmentstatic

static placeBesideSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, distance: Real | NumberLike, left: Bool | BoolLike, result?: Pin | null): Pin

Places a pin beside a line segment at the specified ratio, offset perpendicular to the segment by the specified distance. The pin is offset to the left or right depending on left. The pin's orientation is not modified. If p1 and p2 coincide, the pin is placed at p1.

p1
The starting point of the segment.
p2
The ending point of the segment.
ratio
The position along the segment (0 to 1).
distance
The perpendicular distance to offset from the segment.
left
If true, the pin is offset to the left of the segment direction; if false, to the right.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned beside the segment at the specified ratio and perpendicular offset.

placeInBoxstatic

static placeInBox(anchorX: Real | NumberLike, anchorY: Real | NumberLike, box: Box | ShapeLike, xOriented: Bool | BoolLike, result?: Pin | null): Pin

Places a pin within a box at the specified anchor coordinates. The orientation can be aligned with either the X-axis or Y-axis of the box.

anchorX
The horizontal position within the box (0 to 1, where 0 is left edge and 1 is right edge).
anchorY
The vertical position within the box (0 to 1, where 0 is bottom edge and 1 is top edge).
box
The box in which to place the pin.
xOriented
If true, the orientation is aligned with the X-axis; otherwise aligned with the Y-axis.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned within box at the specified anchor coordinates.

placeInRectanglestatic

static placeInRectangle(anchorX: Real | NumberLike, anchorY: Real | NumberLike, target: Rectangle | ShapeLike, xOriented: Bool | BoolLike, result?: Pin | null): Pin

Places a pin within a rectangle at the specified anchor coordinates. The orientation can be aligned with either the X-axis or Y-axis of the rectangle.

anchorX
The horizontal position within the rectangle (0 to 1, where 0 is left edge and 1 is right edge).
anchorY
The vertical position within the rectangle (0 to 1, where 0 is bottom edge and 1 is top edge).
target
The rectangle in which to place the pin.
xOriented
If true, the orientation is aligned with the X-axis; otherwise aligned with the Y-axis.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned within target at the specified anchor coordinates.

placeOnArcstatic

static placeOnArc(center: Point | VectorLike, radius: Real | NumberLike, startDir: Vector | VectorLike, endDir: Vector | VectorLike, ratio: Real | NumberLike, clockwise: Bool | BoolLike, result?: Pin | null): Pin

Places a pin on an arc at the specified ratio. The pin's orientation is not modified. A ratio of 0 corresponds to the start direction, 1 to the end direction.

center
The center point of the arc.
radius
The radius of the arc.
startDir
The direction from the center to the start of the arc.
endDir
The direction from the center to the end of the arc.
ratio
The position along the arc (0 to 1).
clockwise
The direction from startDir to endDir: clockwise in the mathematical sense (y axis up), so true runs counterclockwise on the screen: the other way than Arcs.arcBetween and Vectors.angle. For example, from the direction (1, 0) to (-1, 0) true passes the top of the circle. To keep one convention, build the arc with Arcs.arcBetween and use Arcs.pointAt, Arcs.pinAt or Arcs.closestPoint.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the arc at the specified ratio.

placeOnCirclestatic

static placeOnCircle(center: Point | VectorLike, radius: Real | NumberLike, angle: Real | NumberLike, result?: Pin | null): Pin

Places a pin on a circle at the specified angle. The pin's orientation is not modified.

center
The center point of the circle.
radius
The radius of the circle.
angle
The angle at which to place the pin on the circle.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the circle at the specified angle.

placeOnSegmentstatic

static placeOnSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, result?: Pin | null): Pin

Places a pin on a line segment at the specified ratio. The pin's orientation is not modified. A ratio of 0 places the pin at p1, 1 at p2, and 0.5 at the midpoint.

p1
The starting point of the segment.
p2
The ending point of the segment.
ratio
The position along the segment (0 to 1).
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin positioned on the segment at the specified ratio.

reversestatic

static reverse(pin: Pin | PinLike, result?: Pin | null): Pin

Reverses the pin's orientation by rotating it 180 degrees. This inverts both orientation components while preserving the orientation's length. The pin's location is unaffected.

pin
The pin to reverse.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with its orientation reversed.

rotateBystatic

static rotateBy(pin: Pin | PinLike, angle: Real | NumberLike, result?: Pin | null): Pin

Rotates the pin's orientation by the specified angle. The pin's location is unaffected.

pin
The pin to rotate.
angle
The angle by which to rotate the orientation.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with its orientation rotated by angle.

rotateLeftstatic

static rotateLeft(pin: Pin | PinLike, result?: Pin | null): Pin

Rotates the pin 90 degrees counterclockwise. The pin's location is unaffected.

pin
The pin to rotate.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin rotated 90 degrees counterclockwise.

rotateRightstatic

static rotateRight(pin: Pin | PinLike, result?: Pin | null): Pin

Rotates the pin 90 degrees clockwise. The pin's location is unaffected.

pin
The pin to rotate.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin rotated 90 degrees clockwise.

scaleBystatic

static scaleBy(pin: Pin | PinLike, scale: Real | NumberLike, result?: Pin | null): Pin

Scales the pin's orientation by multiplying its current length by the specified factor. The pin's location is unaffected.

pin
The pin to scale.
scale
The factor to multiply the orientation length by.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with its orientation scaled by scale.

tipstatic

static tip(pin: Pin | PinLike, result?: Point | null): Point

The tip of a pin: its position plus its orientation vector, i.e. the end of the arrow the pin describes.

Unlike Pins.moveForward (the pin moved forward by a given length), tip returns a point, the pin's own length away from its position.

pin
The pin.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point at the tip of pin.

withLengthstatic

static withLength(pin: Pin | PinLike, length: Real | NumberLike, result?: Pin | null): Pin

Sets the pin's orientation to the specified absolute length, preserving its direction. The pin's location is unaffected.

pin
The pin whose orientation length to set.
length
The target length for the orientation vector.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with its orientation set to length while preserving direction.

withOrientationstatic

static withOrientation(point: Point | VectorLike, direction: Vector | VectorLike, result?: Pin | null): Pin

Sets the pin's orientation to the specified direction. The pin's location is unaffected.

point
The point whose orientation to set.
direction
The new orientation for the pin.
result optional
Optional Pin to write the result into; it is returned. Without it, a new Pin is returned.

Returns A pin with its orientation set to direction.