Rays Rule

Partitions input region using straight path segments in the manner of ‘rays‘. Intersections of ‘ray’ segments with each other are called junctions, and intersections at iregion boundary – entrancesDelaunay Triangulation is used (related to Voronoi Diagram, which is its dual).

Entrances (boundary intersections) are determined by the list of boundary parameters or selections. Junction placement (ray intersections) is determined by sample distribution radius:

rays(boundary_selections, radius) 
 { RegionList } { PathList } { JunctionList }

Alternatively, a number of samples can be specified, and the algorithm tries to guess the sample radius:

rays(boundary_selections, number_of_samples) 
 { RegionList } { PathList } { JunctionList }

Optionally, minimal offset from junctions to the boundary can be provided:

rays(boundary_selections, ..., junction_offset) 
 { RegionList } { PathList } { JunctionList }
  • boundary selections – list of parameter values within the range [0..1]. For example [0, 0.25, 0.5, 0.75] will place entrances at the corners of a square.
  • radius, number_of_samples – minimum radius between any two junctions, and respectively the number of junctions. Also, see Cells Rule for the explanation with one difference: in Cells Rule radius refers to the distance between quarters, rather than junctions ).
  • offset – centres of the junctions is placed with this minimum distance from the boundary.
  • RegionList, PathList, JunctionList – label selector lists (see Grid Rule for explanation).

Select Rule

Re-write incoming geometry to a different set of labels.

select { RegionList }

RegionList – label selector list, list of selector expressions applied on the input shape.

No geometry is modified, only labels are assigned and attributes set. The purpose of this rule is to remove redundancy of repeating the same operations on one label in different selector blocks, for instance:

InputLabel --> place(CENTRE) 
 { 50%: Border1 | else: Border2  } 
 { i("circle", 10) Inserted } 
 { 50%: Border1 | else: Border2  }

can be rewritten as:

InputLabel --> place(CENTRE) 
{ Border } { i("circle", 10) Inserted } { Border } 

Border --> select { 50%: Border1 | else: Border2 }

Rule application makes even more sense when selector expression lists are longer, or when the same label is assigned in a number of different rules.

Cells Rule

Partitions input region into more natural looking “cell-like” quarters that resemble biological cells. Voronoi Diagram partitioning method is used.

Sample radius determines centre of a cell:

{ RegionList } { PathList } { JunctionList }

Alternatively number of samples can be requested and radius best matching radius will be guessed (this is currently a not very accurate procedure):

 { RegionList } { PathList } { JunctionList }

With an optional smoothing parameter:

cells(..., M(smoothing_factor))
 { RegionList } { PathList } { JunctionList }

Symmetry parameter is added at the end and is also optional:

cells(..., S(symmetry_id))
 { RegionList } { PathList } { JunctionList }
  • radius – minimum distance between any two path junctions; larger radius means fewer junctions. Alternatively number_of_samples can be used:
  • number_of_samples – specify actual number of junctions to place within the region. Algorithm tries to take a guess the appropriate radius, however the actual radius than the ideal one for the appropriate number of samples.
  • smoothing_factor – how much should the cells be smoothed by. Smoothing reduces a cell size.
  • symmetry_id
    • 0: no symmetry
    • 1: x symmetry
    • 2: y symmetry
    • 3: x and y symmetry (which is also a boolean AND of 1 and 2)
  • RegionList, PathList, JunctionList – label selector lists, as in Grid Rule.

Boundary Range Selection

Boundary Range Selection List

Selection1 Selection2 ... SelectionN

Selectioni – Selection Entry, can be one of the following:

  • Ranged Selection
  • Special Selection
  • Named Selection

Ranged Selection

Range selection is the most basic type of (range) selection that simply specifies subset of boundary range parametrised on the range [0..num_edges]:

[lower, upper]

lower, upper – values within without boundary range; lower must be less than upper. Value can be specified as a doublepercent, Random Range or named attribute.

Special Selection

upper and lower as described above.

Numbered selection is the synonym to Range Selection (see above):

num[lower, upper]

Edge Angle Selection:

ea[lower, upper]

Angle Range Selection:

ar[lower, upper]

Cardinal Directions Selection:

dir[lower, upper]
  • dir – cardinal direction label,  either “N“, “E“, “S” or “W“.
  • upper, lower are within the range [0..1]

Global Attributes

Global attributes are very similar to alike a constant global value in a general programming language. Attributes assignment as follows:

attribute_name = attribute_value

  • attribute_name –  alphanumeric value, no spaces (should start with a letter).
  • attribute value – a double number, which can be treated as a real number or a boolean value (0 is false)

Insert Rule

Insert a new shape at the boundary.

 { InsertedList } { SubstrateRegionList }
  • value_selection (list of floating numbers) – insert locations parametrised along the input region boundary.
  • InsertedList (label selector list) – specifies a new shape and label
  • SubstrateRegionList (label selector list) – label for the remaining region.

Random Ranges

Random Ranges

Random Integer Range

ri(min_value .. max_value)

Returns a randomly selected integer number from the [min_value, max_value] range at evaluation time using integer uniform distribution.

Random Real (Floating Number) Range
ru(min_value .. max_value)

Returns a randomly selected floating number from the [min_value, max_value] range at evaluation time using uniform distribution.


Insert Operator

Insert operator creates new geometry. Depending on the rule it is either ignored (e.g. Peel rule), optional (Centres of the Grid rule) or required (Insert and Place rules).

i(geometry_path, r1)
i(geometry_path, r1, r2)
  • geometry_path – a string that specifies new geometry to be inserted, either
    • builtin:<primtive_shape>” – a predefined shape based on primitives where <primitive_shape> is either circle, square or rhombus. r1 is the size of the shape. If r2 is specified, it is passed as size2 along y axis; in such case circle becomes an ellipse, and square – a rectangle.
    • iregion:shrink” – iregion is shrunk by r1 and used as the inserted shape
    • iregion:smoothen” – iregion is shrunk by r1 (see above) and then smoothed with r2 weight; if r1 is not given value 0.5 is used.
  • r1, r2 – extra parameters (mentioned above)

Insert a circle with radius 15% of the input region (provided rule accepts shape insertion) into a shape labelled InsertedCircle:

{ i("builtin:circle", %15) InsertedCircle }

…rhombus 20 wide and 15 high:

i("builtin:rhombus", 20, 15)

Label Selectors and Operators

Label Selector List

{ Selector1 | Selector2 | ... SelectorN }

One label selector is chosen for each shape at the rule output (derived shape). More than one may match, but only the first one matching is selected. The last selector SelectorN is expected to be a plain/default selector – otherwise, rule applications fails.

Label Selector

Evaluates to a label, matching condition and optimally additional operations (see below).

A plain selector is simply a label, and it always matches:


Alternatively, if label selection should be limited to a particular condition:

MatchCondition: Label

Additional attribute modifications or shape insertion can be requested before the label:

MatchCondition: SelectorOperatorOperations Label
  • Label – label assigned to a derives shape
  • MatchCondition – a match condition expression should evaluate to true to match the label
  • SelectorOperatorOperations – operations based on selector operators.

Match Conditions

Border Keyword (NEW)

Regions that are touching a boundary at an edge are selected (however, regions sharing a vertex with iregion boundary are not!).

Index Match
idx(x_expr, y_expr)
  • x_expr, y_expr – integer expression that is either a number or a keyword, optionally prefixed with “!” which negates the meaning. Available keywords:
    • odd – all odd indices are selected. Even indices selected with “!odd”
Stochastic Match

Selector is chosen with a probability of percent value. For instance “50%” would accept the label roughly half of the time.

Default Match Keyword

Default match condition always matches (the keyword it can also be omitted).

Selector Operators

Insert Operator

Considered separately.

Set Operator

Creates a new attribute or changes a propagated attribute that is inherited from the rule input shape. For instance type attribute is assigned using set.

set(attribute_name, attribute_value)
  • attribute_name – an attribute name, of the same format as shape label.
  • attribute_value – a number or a string. The number is stored in double precision floating point format.


Selects Label2 half of the time, and Label1 and Label3 equally quarter of the time each:

{ 25%: Label1 | 50%: Label2 | else: Label3 }

Checkerboard pattern:

{ idx(odd, odd): LabelWhite | 
  idx(!odd, !odd): LabelWhite | LabelBlack }

Change path width to a third for any further productions on QuarterLabel:

{ set(path_width, %33.3) QuarterLabel }

Scatter Rule

Scatters objects within the input region.

“Place” an object at the centre of input region:

scatter(CENTRE) { ShapeSelector }

Scatter objects along the boundary selection (each edge treated separaely):

scatter(EDGE_SELECTION, density, boundary_selection, offset) { ShapeSelector }

Scatter objects along the boundary boundary selection (continuous selection is not separated into edges):

scatter(BOUNDARY_SELECTION, density, boundary_selection, offset) { ShapeSelector }

Scatter using Poisson distribution (the same method used in Disperse Components plugin):

scatter(density, offset) { ShapeSelector }


  • density – a floating number, which if prefixed with R will be a radius “R radius_value” (minimal distance between any two samples), and when not – is the desired number of samples to be scattered. It is recommended to give this parameter in the radius mode.
  • boundary_selection – subset of the input region boundary
  • offset – offset from the input region boundary. When 2D (Poisson) distribution is used – radius_value is passed as an offset.