Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Point Helper Reference

Point helpers turn the geometry you have already cut into reusable coordinates. They power angle + point cuts, point-pair slices, functions, and optimizer targets. Most helpers resolve to a 3D point once the referenced tiers exist; Point(x, y, z) is the outlier that simply returns the literal coordinate you supply.

Literal point (Point)

Point(x, y, z) returns an explicit point without relying on any cut geometry. Coordinates share the same frame as other helpers: origin at the stone center, +Z toward the crown.

Note: Point should be used sparingly, as it is absolute and not sensitive to the geometry of the cut. One good use is in functions: it is used in the Oval() system function.

name = "Literal Anchor"

anchor = Point(0, 0, 1.1)
print("Anchor:", anchor)
show(anchor, "orange")
P1 0 @ 42 : anchor

Center point (cp())

cp() sits on the stone's center axis. It always returns (0, 0, 1) when the active side is the crown (up) and (0, 0, -1) when the active side is the pavilion (down).

name = "Center Anchors"

// Mark the culet to check alignment
print("Center point:", cp())
show(cp(), "blue")
P1 0 @ 41 : cp() x8

Girdle points (gp())

gp() identifies the Girdle Point that sits “in front” of the requested index/angle. It strictly returns existing vertices from the stone's geometry.

Inside a cut command, it borrows the current index, angle, and side automatically. Elsewhere, you must supply an options object gp({ index: ..., angle: ... }) so the helper knows where to search.

Height Selection Logic

To find the correct girdle line, gp() analyzes the stone's existing "angled" facets (facets that are neither vertical girdle facets nor horizontal table/culet facets):

  1. It identifies the Z-extremes of all Angled Pavilion Facets and Angled Crown Facets.
  2. It assumes the girdle lies at the interface of these cuts.
  3. It selects a target height based on the active side:
    • Pavilion cuts (Down): Targets the top (max Z) of the angled pavilion facets. (Fallback: bottom of crown facets).
    • Crown cuts (Up): Targets the bottom (min Z) of the angled crown facets. (Fallback: top of pavilion facets).

This ensures that even if the girdle has multiple tiers or steps, gp() locks onto the height where the main cone of the stone currently meets the girdle.

Search Plane Logic

Once the correct height is found, gp() scans the vertical girdle vertices at that height. It selects the vertex that the search plane would "hit first" (maximum projection).

[!NOTE] ProFacet identifies girdle facets by their orientation. Facets with a vertical tilt of less than 0.0001 (1e-4) are considered part of the girdle and included in the gp() search.

name = "Girdle Pickup"
gear = 96
size = 1.0

P1 0 @ 45 : cp() x8
G1 0 @ 90 : size x16
C1 6 @ 34 : mp(P1, G1) + girdle x16

// Pick up the girdle point at index 0 explicitly
print("GP 0:", gp({ index: 0 }))
show(gp({ index: 0 }), "cyan")

// pavilion-side (bottom) girdle point (Still returns High GP by default)
print("GP 24:", gp({ index: 24 }))
show(gp({ index: 24 }), "orange")

For uneven girdle lines, there is some extra logic that decides if a point can be a true girdle point. If this fails for some reason, the user can use the mp() function, explained next.

Meet points (mp)

mp searches for the intersection of tiers you name. Pass one or more tiers to include, prefix a tier with ! to exclude it, and ProFacet finds the point that is the first to satisfy the filters. Think of an initial cutting plane far from the stone, that moves towards the center until a valid point is found.

mp respects the current index and angle context, when used inside a cut command. When used outside of a cut command, you can pass an options object (explained later) to jump to a specific tooth and perform the meetpoint search at that tooth.

Matching tiers vs. explicit indices

Think of mp as a facet filter: every positive tier you list must participate in the actual meet, while negated tiers must be absent. There are often several equivalent ways to describe the same vertex.

//  A few common patterns
mp(C1)                              // single-tier meet
mp(C1, G1)                          // multiple tiers
mp(C1, C1)                          // requires C1 to be part of the meet at least twice
mp(C1, G1, !C2)                     // exclude an unwanted tier
mp(C1:12, C2:16)                    // insist on specific cut indices
mp(C1, { index: 3, angle: 45.0 })   // explicit tooth/angle override

Symmetry means those filters can match multiple physical points. That’s usually fine inside a facet command because the base index and angle narrow the choice. If you provide an explicit array of indices (e.g., P1 [0, 10, 20] ...), the engine ignores symmetry and uses the first element of the array as the base index for resolution. Outside of a cut—show(mp(C1)) or helper = mp(G1)—add an options object to keep things deterministic:

Relying on explicit indices like mp(C1:12, C2:16) ties the design to a particular gear/symmetry combination, so prefer tier filters without indices when you can.

Examples

name = "Meetpoint Examples"
gear = 96
size = 1.0
girdle = Vector(0, 0, 0.03)

P1 3 @ 41.0 : cp() x8
G1 3 @ 90.0 : size
P2 0 @ 38 : gp()
C1 3 @ 35.0 : mp(P1, P2) + girdle
C2 0 @ 38.0 : gp()
C3 2 @ 33.0 : gp()

T 0 @ 0 : mp(C2) x1

print("Blue mp:", mp(C2,T))
show(mp(C2,T), "blue")
show(mp(C1, C2, !G1), "purple")
show(mp(C1, C2, G1, !C3), "red")
show(mp(C1, C2, G1), "orange")

Edge references (edge)

edge returns the shared edge between two previously cut facets. You pass tier/index pairs (edge(C1:0, C1:6)), and the helper returns an array of both endpoints [p1, p2] so other helpers can work with them. The points are sorted by X, then Y, then Z coordinate, ensuring p1 is always the "smaller" point geometrically (e.g., further left).

C1 0 @ 32 : 0.08 x6
edge_arr = edge(C1:0, C1:16)
print("Edge Start:", edge_arr[0])
print("Edge End:", edge_arr[1])
show(edge_arr[0], "red")
show(edge_arr[1], "blue")

Use edge only after both referenced facets exist; otherwise the interpreter raises an error telling you which tier/index is missing.

Edge interpolation (ep)

ep walks along an edge. Supply an edge(...) (or any array of 2 points) plus a factor between 0.0 and 1.0. Zero sticks to the first point, one sticks to the second, and any other value interpolates in between.

name = "Edge Interpolation"
size = 1.0

C1 0 @ 32 : 0.08 x16
G1 0 @ 90: size

e = edge(C1:0, C1:6)
mid_edge = ep(e, 0.5)

print("Start:", e[0])
print("End:", e[1])
print("Midpoint:", mid_edge)

show(e[0], "red")
show(e[1], "blue")
show(mid_edge, "purple")

ep([mp(C1), mp(C2)], 0.25) is equally valid when you want a point partway between two meetpoints.

Project Z (prz)

prz projects a point vertically onto the stone or a specific facet. This is useful for transferring points from a 2D layout (like ep on a flat plane) onto the 3D surface of the gem.

  • prz(pt): Drops the point vertically onto the stone's surface (crown or pavilion depending on the active side).
  • prz(pt, "Tier:Index"): Projects the point onto the infinite plane of the specified facet.

Fred point (fred)

fred finds the point on a target edge where a construction line crosses it, as seen from above (XY projection). It takes two lines defined by four points: the first pair (p1, p2) is the construction line, and the second pair (p3, p4) is the target edge. The function projects both lines onto the XY plane, finds their intersection, and returns the full 3D point on the target edge at that crossing.

  • fred(p1, p2, p3, p4): Intersects line p1–p2 with line p3–p4 in XY projection, returns the 3D point on p3–p4.
  • fred(p1, p2, edge): Same operation, but accepts an edge(...) array as the target instead of two separate points.

If the two lines are parallel in the XY projection, fred raises an error.

name = "Fred Point Demo"
gear = 96

P1 0 @ 42 : cp() x8
G1 0 @ 90 : size x16
C1 6 @ 34 : mp(P1, G1) + girdle x16

// Find where a construction line crosses an edge
e = edge(C1:0, C1:6)
a = mp(P1, { index: 0 })
b = mp(P1, { index: 12 })

crossing = fred(a, b, e)
show(crossing, "red")
print("Fred point:", crossing)

[!NOTE] fred is named in honor of Fred van Sant, whose gemstone designs make extensive use of this kind of geometric construction—finding where visual construction lines intersect existing cut edges to precisely place new facets.

Index, Angle, and Side override

You can pass an options object to mp or gp to pin a helper to a specific index, angle, or side: mp(P1, { index: 12, angle: 39.4 }).

  • index: The integer gear index.
  • angle: Optional angle override. If omitted, the helper uses the current angle context.
  • side: Optional side override ("Up"/"Crown" or "Down"/"Pavilion"). Supported by gp only. While gp() defaults to the high girdle point, this context is still used for resolving index-to-azimuth translations.
name = "Attachments"
gear = 96
girdle = Vector(0, 0, 0.03)

P1 0 @ 41.5 : 0.18 x8

// Force Crown-side girdle point even if outside a Crown cut
top_edge = gp({ index: 12, side: "Up" })
print("Top edge point:", top_edge)
show(top_edge, "green")

C1 0 @ 32.2 : top_edge + girdle x8

Grid points (grid)

grid(x_n, y_n, x, y) divides the bounding box of the stone into a grid and returns the coordinates of the specified point. It's useful for step cuts where you want to create evenly spaced facets across the width or length of the stone.

  • x_n: Number of divisions in the X direction (columns).
  • y_n: Number of divisions in the Y direction (rows).
  • x: The X index of the point (0 to x_n, inclusive).
  • y: The Y index of the point (0 to y_n, inclusive).

The function calculates the bounding box of the current geometry and returns a point at (pos_x, pos_y, 0.0) where:

  • pos_x = min_x + (width / x_n) * x
  • pos_y = min_y + (height / y_n) * y

Explicit bounding box

grid(x_n, y_n, x, y, pt1, pt2) uses an explicit bounding box defined by two corner points instead of the stone's geometry. This is useful when you want to subdivide a specific region rather than the entire stone.

  • pt1, pt2: Two point expressions defining opposite corners of the bounding box.

Expressive Grid (surface)

surface(u, v) behaves like grid but projects the point vertically onto the stone's surface (crown or pavilion depending on context) rather than sitting on a flat z-plane. It accepts fractional coordinates 0..1 relative to the stone's bounding box.

  • u: Fractional position (0.0 to 1.0) along the bounding box width (X axis).
  • v: Fractional position (0.0 to 1.0) along the bounding box height (Y axis).
// Top center of the bounding box, projected onto facets
p = surface(0.5, 0.5)
print("Surface point:", p)

Like grid, surface accepts an optional custom bounding box: surface(u, v, pt1, pt2).

You can also pass an options object as the last argument to specify which side of the stone to project onto, overriding the machine's current state:

// Project onto the pavilion (down) even if cutting the crown
p_down = surface(0.5, 0.5, { side: "down" })

p_up = surface(0.9, 0.9, { side: "up" })

show(p_up, "blue")
show(p_down, "yellow")