Using APL for Gemstone Design

⚠️ Experimental: APL support is experimental and under active development. The engine, syntax, and available functions may change without notice. If you encounter issues, please report them — and remember, this is a playground for the mathematically adventurous.

ProFacet supports three scripting languages for designing gemstones: FSL (the purpose-built spec language), Lua (a general-purpose scripting language), and APL — a mathematical notation turned programming language.

Why APL?

APL is not for everyone. It's a notation designed by mathematicians, for mathematicians. Where FSL and Lua offer convenience functions like mp(), cp(), and TierAP(), APL gives you raw linear algebra primitives and expects you to build everything yourself.

If that sounds appealing, read on. If you prefer a guided experience, stick with FSL or Lua.

What APL brings:

• Concise mathematical notation — A complete gemstone design in 4 lines
• Array-oriented thinking — Planes, vertices, and transforms are all matrices
• No magic — Every computation is explicit; you see exactly what the math does
• Live playground — Run APL directly in the handbook with instant 3D preview

Getting Started

In the interactive playground (found throughout this handbook), click the APL tab. The playground wraps your code with an auto-injected gemstone engine that provides the core functions. Your code runs between the header (which defines the engine) and the footer (which exports the stone to the 3D viewer).

Tutorial: Building Cuts Step by Step

Step 1: A Single Horizontal Cut

The simplest possible cut — a single horizontal table facet:

'Table' cut (0 0 1) at 0.09

That's it. Three numbers:

• 0 — angle: 0° (horizontal)
• 0 — index: gear position 0 (doesn't matter for horizontal, but required)
• 1 — direction: up (crown side)

at 0.09 sets the depth. This cuts one flat plane off the top of the rough stone.

Step 2: A Single Angled Cut

Now tilt that facet and aim it downward:

'P1' cut (37.5 0 ¯1) at ¯1.0

• Angle 37.5° — the facet tilts inward
• Index 0 — at gear position 0
• Direction ¯1 — pavilion (down)

Notice ¯1 — that's APL's high minus (negative sign), distinct from the subtraction operator -. This creates a single angled facet on the pavilion side.

Step 3: Adding Symmetry

One facet is lonely. Let's repeat it 8 times around the stone:

'P1' cut (37.5 (0 sym 8) ¯1) at ¯1.0

The only change: scalar 0 → 0 sym 8. The sym function generates 8 evenly-spaced gear indices around the stone. With Gear ← 96 (the default), 0 sym 8 produces indices 0 12 24 36 48 60 72 84.

Step 4: Adding Mirrors

For a brilliant cut, each facet has a mirror reflection:

'P1' cut (37.5 (mir 3 sym 8) ¯1) at ¯1.0

mir adds reflected indices: mir 3 sym 8 produces 16 indices (8 original + 8 mirrored). Index 3 instead of 0 ensures the mirrors don't overlap — 0 mirrors onto itself.

Step 5: Offset Indices

Not all facets start at index 0. For example, star facets on the crown sit between the main facets:

'P1' cut (37.5 (mir 0 sym 8) ¯1) at ¯1.0
'G1' cut (90 (mir 0 sym 8) ¯1) at 1.0
'C1' cut (25 (mir 3 sym 8) 1) at 0.5

Notice 3 sym 8 — the 3 offsets the indices so these crown facets sit rotated relative to the pavilion mains. The girdle (G1 at 90°) gives the stone its outline.

Step 6: Meetpoints

Instead of specifying a fixed depth, you can cut to where existing facets meet:

⍝ Round Brilliant — 4 lines, zero variables
'P1' cut (37.5 (mir 3 sym 8) ¯1) at ¯1.0
'G1' cut (90 (mir 3 sym 8) ¯1) at 1.0
'C1' cut (25 (mir 3 sym 8) 1) at (zOff05 V on tier 'P1')
'Table' cut (0 (0 sym 1) 1) at 0.09

The crown (C1) cuts to a meetpoint instead of a fixed depth:

• V on tier 'P1' — find vertices that touch the pavilion tier
• zOff05 — add a small girdle offset (0.05) to those vertices
• at detects the vertex matrix and auto-finds the meetpoint

The tier function looks up a tier's planes by name — so V on tier 'P1' finds vertices touching the pavilion mains without needing to save them to a variable first.

Reading the Cut Syntax

Each line follows this pattern:

'NAME' cut (ANGLE (INDICES) DIRECTION) TARGET

Assignment is optional — only save the result if you need it later (e.g., for V on).

Breaking down a pavilion cut:

'P1' cut (37.5 (mir 3 sym 8) ¯1) at ¯1.0
⍝     │     │              │    │  │
⍝     │     │              │    │  └─ depth = 1.0 (pavilion depth)
⍝     │     │              │    └──── at = target (depth, point, or vertices)
⍝     │     │              └───────── ¯1 = pavilion direction (down)
⍝     │     └──────────────────────── mir 3 sym 8 = 16 indices (8-fold + mirrors)
⍝     └────────────────────────────── 37.5° tilt angle

A crown cut with meetpoint:

'C1' cut (25 (mir 3 sym 8) 1) at (zOff05 V on tier 'P1')
⍝        │    │              │  │
⍝        │    │              │  └── zOff05 offsets the vertices, at auto-finds meetpoint
⍝        │    │              └───── 1 = crown direction (up)
⍝        │    └──────────────────── 16 mirrored indices
⍝        └──────────────────────── 25° crown angle

Settings

The engine provides three variables you can set at the top of your code:

Gear ← 96         ⍝ Number of gear teeth (default 96)
Name ← 'My Stone'  ⍝ Name of the design
RI ← 1.54         ⍝ Refractive index (default 1.54, quartz)

Gear controls the angular resolution of the indexing system. The standard is 96 teeth. All indices run from 0 to Gear-1, and functions like sym and mir use Gear for modular arithmetic.

Cutting Notes

Use note to attach instructions to any tier. Notes appear in the printable cutting diagram.

'P1' note 'Cut pavilion mains first'
'G1' note 'Polish to 600 grit'
'C1' note 'Meet P1 and G1 at girdle'

Notes are separate from cut — add them anywhere after the tier has been created. Each tier can have one note; if you call note again on the same tier, both entries are included.

Tips for APL Users

• ⎕IO ← 0 is set automatically — all indexing is zero-based
• The gear has Gear teeth (default 96) — indices run from 0 to Gear-1
• Direction is ¯1 for pavilion, 1 for crown
• V is a global variable holding all current vertices
• Stone is a global N×4 matrix of all planes
• Tier names are the left argument — 'P1' cut ... names the tier directly; use tier 'P1' to reference it later

How It Works

Unlike FSL and Lua, the APL engine does not call into ProFacet's Rust/WASM engine. Instead, it implements the entire gemstone computation in pure APL — half-space intersection, vertex solving via Cramer's rule, and meetpoint projection. This means:

1. No built-in geometry helpers — There is no mp() or cp() magic function. The engine provides lower-level primitives that you compose.
2. Everything is a matrix — A stone is an N×4 matrix where each row is [nx ny nz d] (a half-space plane). Vertices are an M×3 matrix.
3. You build the cuts — The cut function adds planes to the stone and recomputes vertices. You control the angle, symmetry, and depth directly.

The APL Gemstone Engine

The following code is automatically injected before your APL code runs. It's shown here in full so you can understand every function available to you.

Index Generation

⍝ Generate gear indices with symmetry
⍝ Usage: base_index sym fold_count
⍝ Example: 3 sym 8 → 3 15 27 39 51 63 75 87
sym ← { Gear | ⍺ + (Gear÷⍵) × ⍳⍵ }

⍝ Mirror indices (adds reflections)
⍝ Usage: mir base_indices
⍝ Example: mir 3 sym 8 → 3 15 27 39 51 63 75 87 93 81 69 57 45 33 21 9
mir ← { ∪ Gear | ⍵ , Gear - ⍵ }

sym generates evenly-spaced indices around the gear. mir adds mirror reflections. Together, mir 3 sym 8 produces 16 indices for an 8-fold symmetric cut with mirrors.

Normal Generation

⍝ NGen: Generate 3D normal vectors from (angle, indices, direction)
⍝ Returns an N×3 matrix of unit normals
∇ R ← NGen args;t;I;d;A;T
  (t I d) ← args
  A ← ○ 2 × I ÷ Gear        ⍝ Gear index → radians
  T ← ○ t ÷ 180              ⍝ Tilt angle → radians
  R ← ⍉ (3 , ≢I) ⍴ ((1○T)×2○A) , ((1○T)×1○A) , ((≢I)⍴d×2○T)
∇

NGen converts (angle, gear_indices, direction) into 3D unit normals. The direction d is ¯1 for pavilion (pointing down) or 1 for crown (pointing up).

Vertex Computation (Cramer's Rule)

⍝ 3×3 determinant for batched matrices
det3v ← { +/ ⍵[;0;] × (⍵[;1;1 2 0]×⍵[;2;2 0 1]) - ⍵[;1;2 0 1]×⍵[;2;1 2 0] }

⍝ Generate all 3-element combinations from 0..n-1
∇ R ← comb3 n;all
  all ← ⍉ (n n n) ⊤ ⍳ n*3
  R ← all ⌿⍨ (all[;0] < all[;1]) ∧ all[;1] < all[;2]
∇

⍝ Solve for all vertices of a stone (intersection of 3 half-spaces)
∇ R ← getVertices S; ...
  ⍝ For every combination of 3 planes, solve the 3×3 linear system
  ⍝ using Cramer's rule. Keep only vertices that satisfy ALL planes.
  ...
∇

getVertices finds every point where exactly 3 planes intersect, then filters to keep only those inside the stone (satisfying all half-space constraints). This is the core of the slicer.

Meetpoint and Cut Functions

⍝ firstContact: find the vertex closest to a plane normal
firstContact ← { ⍵[ (0⊃⍒ ⍵ +.× ⍺) ; ] }

⍝ V on T: filter vertices that lie on tier T
∇ R ← V on T
  ⍝ Returns vertices from V that touch the planes in tier T
∇

⍝ args mp V: compute meetpoint (closest vertex to the cutting direction)
∇ R ← args mp V
  R ← (NGen args)[0;] firstContact V
∇

⍝ args at target: compute plane distances from cut parameters
⍝ Handles three target types:
⍝   scalar  → depth (e.g., at 1.0)
⍝   3-vec   → meetpoint (e.g., at pt)
⍝   matrix  → vertices (auto-finds meetpoint)
⍝   2-vec   → angle solve between two points
∇ R ← args at rarg
  ⍝ Returns N×4 matrix: [nx ny nz d] for each cutting plane
∇

⍝ CM operator: "Cut to Meetpoint" with transform
⍝ Usage: args (transform CM) V
∇ R ← args (LO CM) V;pt
  pt ← LO args mp V    ⍝ Find meetpoint, apply transform (e.g., zOff05)
  R ← args at pt        ⍝ Compute plane distances from that point
∇

The Cut Function

⍝ cut: Add named planes to the stone and recompute vertices
⍝ Left arg is the tier name, right arg is the plane matrix
∇ tier ← nm cut planes
  TierCount ← TierCount + 1
  TierNames ← TierNames , ⊂nm
  TierMap   ← TierMap , (≢planes) ⍴ TierCount
  Stone ← Stone ⍪ planes               ⍝ Append new planes
  ⍝ Keep existing vertices that satisfy new constraints
  kept ← V ⌿⍨ ∧/ 1e¯5 ≥ (V +.× ⍉ planes[;0 1 2]) -⍤1 planes[;3]
  ⍝ Solve for new vertices involving the new planes
  newV ← (old_count) solveNew Stone
  V ← urows (kept ⍪ newV)              ⍝ Merge and deduplicate
  tier ← planes
∇

⍝ tier: look up a tier's planes by name
∇ R ← tier nm
  R ← (TierMap = TierNames ⍳ ⊂nm) ⌿ Stone
∇

cut is the main workhorse. The left argument names the tier (e.g., 'P1'), and the right argument is the N×4 plane matrix. It appends half-space planes to Stone, filters existing vertices, solves for new intersections, and updates the global vertex set V.

tier looks up a previously cut tier by name — e.g., tier 'P1' returns the plane matrix for tier P1. This lets you reference tiers without storing them in variables: V on tier 'P1'.

Cutting Notes

⍝ note: attach a cutting instruction to a tier
⍝   'P1' note 'Cut pavilion mains first'
∇ nm note txt
  ⍝ Appends to TierNoteNames and TierNotes vectors
∇

note is separate from cut — call it any time after the tier exists. Notes are exported in the JSON output and appear in ProFacet's printable cutting diagram.

Utility Functions

⍝ zOff05: Add a 0.05 girdle offset to a meetpoint
∇ R ← zOff05 X
  R ← X + 0 0 0.05
∇

⍝ id: Identity (pass-through, used as default transform)
∇ R ← id X
  R ← X
∇

Initial State

⍝ The rough: a 2×2×2 cube defined by 6 half-spaces
Rough ← 6 4 ⍴ 0 0 1 2  0 0 ¯1 2  1 0 0 2  ¯1 0 0 2  0 1 0 2  0 ¯1 0 2
Stone ← Rough
V ← getVertices Stone
TierCount ← 0
TierMap ← 6 ⍴ 0
TierNames ← ⊂'Rough'
CutLog ← 0 3 ⍴ 0

Your code starts with a cube (Rough) and carves it down with cut calls.

CAM Outline Functions

The APL engine includes all ProFacet CAM (Centerpoint–Angle Method) outline functions. These generate girdle preforms with a single function call, just like FSL and Lua. All functions are prefixed with apl to avoid name collisions. Internally, they call cut directly.

Usage

⍝ Simple shapes — single argument
aplRound (43 8)        ⍝ Round with angle 43°, 8-fold symmetry
aplHexagon 43          ⍝ Hexagonal outline
aplOctagon 43          ⍝ Octagonal outline
aplShield 44           ⍝ Shield/kite shape

⍝ Truncated shapes — (angle truncation) or (truncation angle)
aplSquareTr (45 0.35)       ⍝ Truncated square
aplHexTr (42 0.3)           ⍝ Truncated hexagon
aplTriTr (0.35 44)          ⍝ Truncated triangle

⍝ Mirrored variants — add offset parameter
aplSquareTrMir (42 0.5 4)   ⍝ Mirrored truncated square
aplHexTrMir (42 0.3 2)      ⍝ Mirrored truncated hexagon
aplTriTrMir (0.25 42 4)     ⍝ Mirrored truncated triangle

⍝ Cushioned shapes
aplSquareCushTr (2 45 0.40)      ⍝ Cushioned truncated square
aplTriCushTr (0.30 44 2)         ⍝ Cushioned truncated triangle
aplPentCushTr (1 33 0.3)         ⍝ Cushioned truncated pentagon

⍝ Curved shapes
aplTriCurved (45 2 4)       ⍝ Curved trilliant
aplSquareCurved (45 2 4)    ⍝ Curved square

⍝ Rectangles
aplRect (1.6 45)                  ⍝ Rectangle (lwr angle)
aplRectTr (1.6 45 0.30 5)        ⍝ Truncated rectangle
aplRectDblTr (1.6 45 0.60 0.50)  ⍝ Double-truncated rectangle

⍝ Oval
aplOval (42 1.35 6)    ⍝ Oval (angle lwr segmentsPerQuad)

Full Reference

Helper Functions

The CAM functions use these lower-level helpers which are also available for custom designs:

Comparison: FSL vs Lua vs APL

Further Reading

• Quick Start — Build a complete stone step-by-step (with APL playground)
• CAM Outlines — All CAM outline functions with live APL playgrounds
• Functional Programming — FSL, Lua, and APL side-by-side examples
• Using Lua — The Lua scripting reference