Foundations

Welcome to Convex-λ, a functional geometry language designed for precision gemstone faceting. It combines declarative geometry definitions with functional programming concepts.

This chapter covers the fundamental building blocks of the language: syntax, comments, types, and variables.

Comments

Code should be documented. Convex-λ supports both line and block comments.

// This is a single line comment
// It ends at the end of the line

/*
   This is a block comment.
   It can span multiple lines.
   Useful for describing complex logic.
*/

x = 10 // Comments can also appear after code

Types

Convex-λ has a simple but powerful type system.

Numbers

All numbers are double-precision floating point. Integers are treated as floats.

val_a = 42
val_b = 3.14159
val_c = -0.001

Strings

Text is enclosed in double quotes.

name = "Brilliant Cut"
note = "Set girdle width"
assert(name == "Brilliant Cut", "String equality")

Booleans

True or false logic values.

is_visible = true
has_finished = false
assert(is_visible, "Boolean check")

Arrays

Ordered lists of values. Arrays can hold mixed types, but typically hold homogenous data (like a list of Points).

// Array of numbers
fib = [1, 1, 2, 3, 5, 8]
assert(fib[5] == 8, "Array access")

// Array of mixed types (valid but rare)
mixed = [1, "two", true]

Structs

Key-value pairs for grouping data. Keys are identifiers.

config = {
    speed: 100,
    mode: "fast"
}
assert(config.speed == 100, "Struct access")

Variables & Assignments

There are four ways to handle values in Convex-λ, each with a specific purpose.

1. Internal Assignment `=`

Used for intermediate calculations. These values are stored in memory but not sent to the 3D viewer or output log.

width = 10
height = 20
// Calculated but not shown
area = width * height
assert(area == 200, "Area calc")

2. Render Assignment `:=`

This is the primary way to output data. It assigns a value to a variable AND renders it.

If the value is Geometry (Plane, Point, Line), it is added to the "Stone" (the 3D model).
If the value is Data (Number, String), it is printed to the Output Log.

// This calculates a value AND prints it to the Output
total_area := 10 * 20

// This creates a plane AND adds it to the 3D model
// We will cover geometry constructors later.
p1 := Plane(Vector(0,0,1), 5)

Used for "Ghost" rendering. It shows the geometry in the viewer (usually as a wireframe) without adding it to the official intersection list (the Stone). This is useful for visualizing construction lines or helper planes.

// Show a guide plane (ghost) but don't cut the stone
guide_plane ?= Plane(Vector(1,0,0), 0)

4. The Underscore Pattern `_`

Often you want to inspect a value without creating a named variable. We use the underscore _ combined with := to log values directly to the output.

// Log a string
_ := "Starting calculation..."

// Inspect a calculation immediately
_ := 10 + 20 * 4

Configuration

Global configuration statements set up the environment. These are usually placed at the top of your file.

Gear(96)        // Set index gear (default: 96)
RI(1.54)        // Set Refractive Index (default: 1.54)
Mode("deg")     // Set angle mode (default: "deg")
// Mode("index") is automatically set when Gear() is called.

Basic Arithmetic

Standard arithmetic operators apply to numbers.

a = 10 + 5   // 15
assert(a == 15, "+")

b = 10 - 5   // 5
assert(b == 5, "-")

c = 10 * 5   // 50
assert(c == 50, "*")

d = 10 / 5   // 2
assert(d == 2, "/")

e = 10 % 3   // 1 (Modulo)
assert(e == 1, "%")

f = 2 ^ 3    // 8 (Power)
assert(f == 8, "^")

The standard library provides common math functions.

import "std"

root = sqrt(16)   // 4
assert(root == 4, "sqrt")

val  = abs(-10)   // 10
assert(val == 10, "abs")

s    = sin(PI/2)  // 1
assert(abs(s - 1) < 0.0001, "sin")

c    = cos(0)     // 1
assert(c == 1, "cos")

In the next chapter, we will explore the powerful operator system that allows these math operations to work on Vectors, Points, and Arrays.

Convex-λ Documentation