qmsh
All Rights Reserved. © Codemine-Ind. → Last Updated: 2020-10-05
beta
V0 (beta)

QMSH

→ the proceduralite's modelling kernel


Quick-Mesh Scripting Language
User Reference Manual



K. Edum-Fotwe
Codemine-Ind.

Introduction



NOTE: THIS DOCUMENT IS IN WORKING-DRAFT STATE.

This reference manual documents the set of symbols defined by the Quick-Mesh Scripting Language - which is the simple geometric shape-grammar employed by the Quick-Mesh Procedural Modelling Kernel in order to define polyhedral mesh.

Foremost: Quick-Mesh aims to be intuitive, concise and flexible.

For each symbol in the language this document provides descriptive notes explaining the functional behaviour alongside instructions to clarify usage.

This document begins with details of the language's key-concepts and the types of kernel entity exposed by the grammar. This document then enumerates the symbols defined within each of the kernel's procedural modules. Note: these modules (classes-of-operation) correspond to the headings in the left-hand menu.

Advanced language topics (such as parametric-control and user-defined-functions) are then detailed. Finally this document closes with a glossary of terms.

NOTE: THIS DOCUMENT IS IN WORKING-DRAFT STATE.

Key Concepts



This section covers important concepts in the QMSH grammar. It defines key terms that express aspects of the grammar and that appear frequently in this document.

Script
→ 'a set of human-readable statements written in the quick-mesh grammar'
Entity
→ 'an instance of a type of element used in quick-mesh scripts to coordinate generative modelling tasks - such as a numeric entity or a geometric entity (or in OO-parlance an object)'
Variable
→ 'a private dynamically typed placeholder used internally in qmsh scripts to refer to an entity'
Function
→ 'a programmatic construct that enables generative modelling operations to be easily defined, invoked and re-used in the quick-mesh grammar'
Symbolic-Name
→ 'an alpha-numeric character sequence used as a designation for a symbol in qmsh'
Expression
→ 'a component of a statement in a quick-mesh script'
Statement
→ 'a unit of procedural expression in the quick-mesh grammar - akin to the notion of a sentence in languages such as English, French and German'
Parameter
→ 'a public explicitly typed immutable entity used in quick-mesh scripts to expose control over the assembly process to an executing environment - so to define the interface to a script'
Symbolic-Operator
→ 'a special character that maps to a natively supported grammatical operation'
Argument
→ 'an input to a function - or an entity supplied as the input to a function'
Operation
→ 'an umbrella (catch-all) term used in qmsh to refer to some form of operative task'
Operative-Scope
→ 'a term describing the extent of the effect of an operation or group of operations - or the number-of-terms or range-of-symbols affected by an operation - or the hierarchical level/depth of an operation or group of operations'
Inline-vs-Instantiative : Inline Operations and Instantiative Operations
→ 'a way of categorising operations based on whether or not they preserve referential equality - this dichotomy dictates the applicability of operations in varying contexts within the qmsh grammar'
Prefix-vs-Postfix : Pre-Fix and Post-Fix Operative Syntax
→ 'a way of categorising a construct or syntactic mechanism in the qmsh grammar based on the manner in which it is applied - either as a pre-cursor or suffix'
D.O.I.E.O : Declaration-Order-IS-Execution-Order!
→ 'a key principal underlying the ethos of the quick-mesh grammar - which (roughly speaking) dictates that (at any given operative-scope) the order in which symbols are defined and operations are expressed is the order in which they will be evaluated'
PF-DN-SEC : Post-Fix Dot-Notation Sequential-Expression-Chain
→ 'a term to describe the expression of chaining (left-to-right) sequences of operations using dot-notation to symbolise operation concatenation (or in OO-speak method-chaining)'

Type System



Figure 3.0: hierarchical map of the types of entity native to the quick-mesh kernel and grammar.

Numbers & Literals

INT : I
→ Integer - represents a whole number (an integral value).
DBL : D
→ Double - represents a double-precision floating-point decimal number.
LNG : L
→ Long - represents an extended-precision whole number (a large integral value).
BLN : B
→ Boolean - represents a binary logic boolean state (either true or false).
CHR : C
→ Character - represents a singe alpha-numeric ASCII character.
STR : S
→ String - represents a sequence of alpha-numeric ASCII characters (a text literal).

Utility Types

ARY : A
→ Array - represents an ordered collection of entities which acts as a container providing access to individual entities via zero-based indexing.
ET : T
→ Entity-Type - represents the type of an entity.

Grammar Syntax



Statement Types

Figure 4.0: hierarchical map outlining the main types of statement in the quick-mesh grammar.
There are four main types of statement in QMSH - which are used to express generative modelling logic. These are: parameter-definition statements, object-assignment statements, general-action statements and the return statement.

In QMSH parameter-defintions, object-assignments and general-actions are all optional. However the return statement is mandatory for every valid QMSH script.

Each statement is terminated (delimited) by a semi-colon - which acts in a similar manner to a full-stop/period in English. In QMSH a statement may span multiple lines of script source or multiple (typically short) statements may appear on the same line for as long as each is delimited by a semi-colon.

PARAM : Parameter-Definition-Statements
→ 'define public (externally-accessible) immutable entities which act as the interface to a script - enabling control over the assembly process from an executing environment'
ASSIGN : Object-Assignment-Statements
→ 'define private (script-internal) variable entities which provide dynamic temporary holders intermediary elements involved in generative operations'
ACTION : General-Action-Statements
→ 'specify inline operations to apply to previously defined variables'
RETURN : Return-Statements
→ 'specify the result of evaluating a script - i.e. the outcome or output entity'

To reiterate: there are four principal types of statement employed in the QMSH grammar to express generative modelling logic. These are parameter-definition statements (which are used to expose public/external inputs to a script), object-assignment statements (which are used to manage private/internal intermediary variables), general-action statements (which are used to mutate private/internal variables inline) and the return statement (which is used to signal the output of the assembly process). Remember that all statements are delimited (terminated or delineated) by a semi-colon and the only mandatory type of statment in a quick-mesh script is the return statement (all others are optional).

Post-Fix Dot-Notation Sequential-Expression-Chains : PF-DN-SECs

Flexible Functions

Figure 4.1: hierarchical map outlining the main features of flexible-functions in quick-mesh.
Type-Free : Implicitly-Typed Variable-Definitions
→ '...minimise symbolic redundancy in quick-mesh scripts'
FFI : Flexible-Function-Invocation
→ '...an umbrella term for constructs in the quick-mesh grammar targeted at increasing the flexibility with which functions may be invoked'
Post-Fix Specifiers : Post-Fix Operation-Axis-Specifiers
→ '...simultaneously remove potential ambiguity in scripts (by being explicit), reduce symbolic redundancy in scripts (by omitting unused/unnecessary arguments) and expand control in scripts (by extending expressive scope)'
Pre-Fix Modifiers : Pre-Fix Geometric-Primitive Modifier-Symbols
→ '...simultaneously simplify the expression of common polyheral primitive modifications and enable the use of optimised primitive generators in place of heavier weight generalised post-instantiation modifiers'
AAP : Automatic-Action-Promotion (Optional-Parenthesis)
→ '...enables zero-argument functions to be invoked without the superfluous trailing empty parenthesis'
AAL : Automatic-Argument-Linearisation
→ '...enables argument-set re-use amongst function invocations - reducing repetition in scripts'
Case-Insensitivity : Case and Underscore Insensitivity for Built-Ins
→ '...provide the flexibility to express generative logic using upper-case, lower-case, camel-case or any-case conventions depending on one's preference - making the grammar less brittle and more accomadation to varying styles of programmatic expression'
Synonym-Support : Shorthands and Aliasing for Built-Ins
→ '...enable the gramamr's native symbols to be invoked using both compact key-code names and verbose clarifying names - so to serve varying use-cases such as compression relative to exposition'
FFD : Flexible-Function-Definition
→ '...an umbrella term for constructs in the quick-mesh grammar targeted at increasing the flexibility with which functions may be defined'
Auto-Return : Automatic-Implicit-Return
→ '...allows scripts containing a single statement (i.e. simple-sequential-expressions) to omit the return keyword'
Auto-Terminator : Automatic-Implicit-Statement-Terminator
→ '...allows the last statement (in any given operative scope) to omit the final trailing semi-colon'

Native Geometry



Figure 5.0: hierarchical map of the set of geometry generator functions built-into the qmsh grammar.

Polygonal Shapes

Figure 5.1: hierarchical map of the set of functions in qmsh for creating abstract polygonal shapes.
Rectangular Polygons
BOX-2D : Generate 2D Rectangle
→ 'instantiates an axis-aligned 2D rectangular polygonal shape'
B-BOX-2D : Generate 2D Beveled-Rectangle
→ 'instantiates a beveled-corner 2D rectangular polygonal shape'
R-BOX-2D : Generate 2D Rounded-Rectangle
→ 'instantiates a rounded-corner 2D rectangular polygonal shape'

Circular Polygons
CIRCLE : Generate 2D Circle
→ 'instantiates a 2D circular polygonal shape'
OVAL : Generate 2D Oval
→ 'instantiates a 2D elliptic (non-uniformly scaled circle) polygonal shape defined by an axis-aligned box'
ARC : Generate 2D Arc
→ 'instantiates a 2D circular arc polygonal shape'
PIE : Generate 2D Pie
→ 'instantiates a 2D pie segment polygonal shape'
ARCH : Generate 2D Archway
→ 'instantiates a 2D circular archway polygonal shape'
CAP-2D : Generate 2D Capsule
→ 'instantiates a 2D capsule polygonal shape'

Common Polygons
TRIANGLE : Generate 2D Triangle
→ 'instantiates a 2D triangular polygonal shape'
QUADRILATERAL : Generate 2D Quadrilateral
→ 'instantiates a 2D quadrilateral polygonal shape'
PARALLELOGRAM : Generate 2D Parallelogram
→ 'instantiates a 2D parallelogram specified by 3 points which define the first two edges'

Regular Polygons
SQUARE : Generate 2D Square
→ 'instantiates a four (4) sided regular 2D polygon centered at the origin (0,0)'
PENTAGON : Generate 2D Pentagon
→ 'instantiates a five (5) sided regular 2D polygon centered at the origin (0,0)'
HEXAGON : Generate 2D Hexagon
→ 'instantiates a six (6) sided regular 2D polygon centered at the origin (0,0)'
SEPTAGON : Generate 2D Septagon
→ 'instantiates a seven (7) sided regular 2D polygon centered at the origin (0,0)'
OCTAGON : Generate 2D Octagon
→ 'instantiates an eight (8) sided regular 2D polygon centered at the origin (0,0)'
NONAGON : Generate 2D Nonagon
→ 'instantiates a nine (9) sided regular 2D polygon centered at the origin (0,0)'
DECAGON : Generate 2D Decagon
→ 'instantiates a ten (10) sided regular 2D polygon centered at the origin (0,0)'
REG → REGULAR-POLYGON : Generate 2D Regular-Polygon
→ 'instantiates an N-sided regular 2D polygon centered at the origin (0,0)'

Data-Driven Polygons
POLYGON : Generate 2D Cyclic-Polygon
→ 'instantiates a data-driven 2D polygon defined by a set of positional coordinate values'
B-POLYGON : Generate 2D Beveled-Cyclic-Polygon
→ 'instantiates a beveled-corner data-driven 2D polygon defined by a bevel distance and a set of positional coordinate values'
R-POLYGON : Generate 2D Rounded-Cyclic-Polygon
→ 'instantiates a rounded-corner data-driven 2D polygon defined by a round radius, a number of round steps and a set of positional coordinate values'

Symbolic Polygons
CHARACTER-2D : Generate 2D Character-Symbol
→ 'instantiates a 2D symbolic (alpha-numeric) character polygonal shape'
B-CHARACTER-2D : Generate 2D Beveled-Character-Symbol
→ 'instantiates a beveled-corner 2D symbolic (alpha-numeric) character polygonal shape'
R-CHARACTER-2D : Generate 2D Rounded-Character-Symbol
→ 'instantiates a rounded-corner 2D symbolic (alpha-numeric) character polygonal shape'
TEXT-2D : Generate 2D Character-Sequence
→ 'instantiates a 2D symbolic (alpha-numeric) character sequence compound polygonal shape'
B-TEXT-2D : Generate 2D Beveled-Character-Sequence
→ 'instantiates a beveled-corner 2D symbolic (alpha-numeric) character sequence compound polygonal shape'
R-TEXT-2D : Generate 2D Rounded-Character-Sequence
→ 'instantiates a rounded-corner 2D symbolic (alpha-numeric) character sequence compound polygonal shape'

Parametric Paths
LINE : Generate 2D Line
→ 'instantiates a 2D line-segment defined by a start and end position'
O-ARC : Generate 2D Open-Arc
→ 'instantiates a 2D open circular arc polyline path'
O-ARCH : Generate 2D Open-Archway
→ 'instantiates a 2D open circular archway polyline path'

Data-Driven Paths
PATH : Generate 2D Open-Polyline
→ 'instantiates a data-driven 2D polyline path defined by a set of positional coordinate values'
B-PATH : Generate 2D Beveled-Open-Polyline
→ 'instantiates a beveled-corner data-driven 2D polyline path defined by a bevel distance and a set of positional coordinate values'
R-PATH : Generate 2D Rounded-Open-Polyline
→ 'instantiates a rounded-corner data-driven 2D polyline path defined by a round radius, a number of round steps and a set of positional coordinate values'

Polyhedral Solids

Figure 5.2: hierarchical map of the set of functions in qmsh that create solid (volumetric) polyhedra.
Platonic Solids
CUBE : Generate 3D Platonic-Cuboid
→ 'instantiates a 3D axis-aligned cuboidal solid'
TETRAHEDRON : Generate 3D Platonic-Tetrahedron
→ 'instantiates a 3D tetrahedral solid centered at the origin (0,0,0)'
OCTAHEDRON : Generate 3D Platonic-Octahedron
→ 'instantiates a 3D octahedral solid centered at the origin (0,0,0)'
DODECAHEDRON : Generate 3D Platonic-Docedahedron
→ 'instantiates a 3D dodecahedral solid centered at the origin (0,0,0)'
ICOSAHEDRON : Generate 3D Platonic-Icosahedron
→ 'instantiates a 3D icosahedral solid centered at the origin (0,0,0)'
M-CUBE : Generate 3D Manifold-Platonic-Cuboid
→ 'instantiates an axis-aligned 3D manifold cuboidal solid'
M-TETRAHEDRON : Generate 3D Manifold-Platonic-Tetrahedron
→ 'instantiates a manifold 3D tetrahedral solid centered at the origin (0,0,0)'
M-OCTAHEDRON : Generate 3D Manifold-Platonic-Octahedron
→ 'instantiates a manifold 3D octahedral solid centered at the origin (0,0,0)'
M-DODECAHEDRON : Generate 3D Manifold-Platonic-Dodecahedron
→ 'instantiates a manifold 3D dodecahedral solid centered at the origin (0,0,0)'
M-ICOSAHEDRON : Generate 3D Manifold-Platonic-Icosahedron
→ 'instantiates a manifold 3D icosahedral solid centered at the origin (0,0,0)'

Axis-of-Revolution Solids
CONE : Generate 3D Cone
→ 'instantiates a 3D conic solid centered at the origin (0,0,0)'
CYLINDER : Generate 3D Cylinder
→ 'instantiates a 3D cylindrical solid centered at the origin (0,0,0)'
CYLICONE : Generate 3D Cyclicone
→ 'instantiates a 3D parametric conic-cylindrical solid centered at the origin (0,0,0)'
SPHERE : Generate 3D Sphere
→ 'instantiates a 3D polar-sphere solid centered at the origin (0,0,0)'
CAPSULE : Generate 3D Capsule
→ 'instantiates a 3D polar-capsule solid centered at the origin (0,0,0)'
ELLIPSOID : Generate 3D Ellipsoid
→ 'instantiates a 3D polar-ellipsoid solid (a non-uniformly scaled sphere) centered at the origin (0,0,0)'
TORUS : Generate 3D Torus
→ 'instantiates a 3D toroidal solid defined by a major and a minor circle and centered at the origin (0,0,0)'

Fixed-Form Solids
PYRAMID : Generate 3D Pyramid
→ 'instantiates a 3D fixed-form pyramid solid centered at the origin (0,0,0)'
GABLE : Generate 3D Gable
→ 'instantiates a 3D fixed-form gable solid centered at the origin (0,0,0)'
DIAMOND : Generate 3D Diamond
→ 'instantiates a 3D fixed-form diamond solid centered at the origin (0,0,0)'
WEDGE : Generate 3D Wedge
→ 'instantiates a 3D fixed-form wedge solid centered at the origin (0,0,0)'
BRACKET : Generate 3D Bracket
→ 'instantiates a 3D fixed-form right-angled bracket solid centered at the origin (0,0,0)'

Parametric Solids
TAPER-TOP-BOX : Generate 3D Taper-Top-Box
→ 'instantiates a parametric 3D taper-top parallax building-block solid'
ROUND-TOP-BOX : Generate 3D Rounded-Taper-Top-Box
→ 'instantiates a parametric 3D rounded-taper-top parallax building-block solid'
BEZIER-TOP-BOX : Generate 3D Bezier-Taper-Top-Box
→ 'instantiates a parametric 3D bezier-taper-top parallax building-block solid'

Polar-Variant Solids
P-CONE : Generate 3D Polar-Cone
→ 'instantiates a 3D polar conic solid centered at the origin (0,0,0)'
P-CYLINDER : Generate 3D Polar-Cylinder
→ 'instantiates a 3D polar cylindrical solid centered at the origin (0,0,0)'
P-CYLICONE : Generate 3D Polar-Cylicone
→ 'instantiates a 3D polar parametric conic-cylindrical solid centered at the origin (0,0,0) '

Capped-Variant Solids
C-SPHERE : Generate 3D Capped-Sphere
→ 'instantiates a 3D flat-topped (capped) spherical solid centered at the origin (0,0,0)'
C-CAPSULE : Generate 3D Capped-Capsule
→ 'instantiates a 3D flat-topped (capped) capsule solid centered at the origin (0,0,0)'
C-ELLIPSOID : Generate 3D Capped-Ellipsoid
→ 'instantiates a 3D flat-topped (capped) ellipsoidal solid centered at the origin (0,0,0)'

Beveled-Variant Solids
B-CUBE : Generate 3D Beveled-Cuboid
→ 'instantiates a 3D beveled (chamfered-edge) cuboidal solid'
B-CONE : Generate 3D Beveled-Cone
→ 'instantiates a 3D beveled (chamfered-edge) conic solid centered at the origin (0,0,0)'
B-CYLINDER : Generate 3D Beveled-Cylinder
→ 'instantiates a 3D beveled (chamfered-edge) cylindrical solid centered at the origin (0,0,0)'
B-CYLICONE : Generate 3D Beveled-Cylicone
→ 'instantiates a 3D beveled (chamfered-edge) conic-cylindrical solid centered at the origin (0,0,0)'
B-PYRAMID : Generate 3D Beveled-Pyramid
→ 'instantiates a 3D beveled (chamfered-edge) fixed-form pyramid solid centered at the origin (0,0,0)'
B-GABLE : Generate 3D Beveled-Gable
→ 'instantiates a 3D beveled (chamfered-edge) fixed-form gable solid centered at the origin (0,0,0)'
B-WEDGE : Generate 3D Beveled-Wedge
→ 'instantiates a 3D beveled (chamfered-edge) fixed-form wedge solid centered at the origin (0,0,0)'
B-DIAMOND : Generate 3D Beveled-Diamond
→ 'instantiates a 3D beveled (chamfered-edge) fixed-form diamond solid centered at the origin (0,0,0)'
B-BRACKET : Generate 3D Beveled-Bracket
→ 'instantiates a 3D beveled (chamfered-edge) fixed-form right-angled bracket solid centered at the origin (0,0,0)'

Rounded-Variant Solids
R-CUBE : Generate 3D Rounded-Cuboid
→ 'instantiates a 3D rounded (smooth-edged) cuboidal solid'
R-CONE : Generate 3D Rounded-Cone
→ 'instantiates a 3D rounded (smooth-edged) conic solid centered at the origin (0,0,0)'
R-CYLINDER : Generate 3D Rounded-Cylinder
→ 'instantiates a 3D rounded (smooth-edged) cylindrical solid centered at the origin (0,0,0)'
R-CYLICONE : Generate 3D Rounded-Cylicone
→ 'instantiates a 3D rounded (smooth-edged) conic-cylindrical solid centered at the origin (0,0,0)'
R-PYRAMID : Generate 3D Rounded-Pyramid
→ 'instantiates a 3D rounded (smooth-edged) fixed-form pyramid solid centered at the origin (0,0,0)'
R-GABLE : Generate 3D Rounded-Gable
→ 'instantiates a 3D rounded (smooth-edged) fixed-form gable solid centered at the origin (0,0,0)'
R-WEDGE : Generate 3D Rounded-Wedge
→ 'instantiates a 3D rounded (smooth-edged) fixed-form wedge solid centered at the origin (0,0,0)'
R-DIAMOND : Generate 3D Rounded-Diamond
→ 'instantiates a 3D rounded (smooth-edged) fixed-form diamond solid centered at the origin (0,0,0)'
R-BRACKET : Generate 3D Rounded-Bracket
→ 'instantiates a 3D rounded (smooth-edged) fixed-form right-angled bracket solid centered at the origin (0,0,0)'

Sub-Divided-Variant Solids
S-CUBE : Generate 3D Sub-Divided-Cuboid
→ 'instantiates a 3D axis-aligned bi-linearly sub-divided cuboidal solid'
S-CONE : Generate 3D Sub-Divided-Cone
→ 'instantiates a 3D bi-linearly sub-divided conic solid centered at the origin (0,0,0)'
S-CYLINDER : Generate 3D Sub-Divided-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided cylindrical solid centered at the origin (0,0,0)'
S-CYLICONE : Generate 3D Sub-Divided-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided conic-cylindrical solid centered at the origin (0,0,0)'
S-CAPSULE : Generate 3D Sub-Divided-Capsule
→ 'instantiates a 3D bi-linearly sub-divided capsule solid centered at the origin (0,0,0)'
O-CUBE : Generate 3D Octant-Cuboid
→ 'instantiates a 3D axis-aligned octant-split cuboidal solid'
M-O-CUBE : Generate 3D Manifold-Octant-Cuboid
→ 'instantiates a 3D axis-aligned manifold octant-split cuboidal solid'

Hybrid-Combinatorial-Variant Solids
B-O-CUBE : Generate 3D Beveled-Octant-Cuboid
→ 'instantiates a 3D beveled (chamfered-edge) octant-split cuboidal solid'
R-O-CUBE : Generate 3D Rounded-Octant-Cuboid
→ 'instantiates a 3D rounded (smooth-edged) octant-split cuboidal solid'
B-P-CONE : Generate 3D Beveled-Polar-Cone
→ 'instantiates a 3D beveled (chamfered-edge) polar conic solid centered at the origin (0,0,0)'
B-P-CYLINDER : Generate 3D Beveled-Polar-Cylinder
→ 'instantiates a 3D beveled (chamfered-edge) polar cylindrical solid centered at the origin (0,0,0)'
B-P-CYLICONE : Generate 3D Beveled-Polar-Cylicone
→ 'instantiates a 3D beveled (chamfered-edge) polar conic-cylindrical solid centered at the origin (0,0,0)'
R-P-CONE : Generate 3D Rounded-Polar-Cone
→ 'instantiates a 3D rounded/smooth polar conic solid centered at the origin (0,0,0)'
R-P-CYLINDER : Generate 3D Rounded-Polar-Cylinder
→ 'instantiates a 3D rounded/smooth polar cylindrical solid centered at the origin (0,0,0)'
R-P-CYLICONE : Generate 3D Rounded-Polar-Cylinder
→ 'instantiates a 3D rounded/smooth polar conic-cylindrical solid centered at the origin (0,0,0)'
S-P-CONE : Generate 3D Sub-Divided-Polar-Cone
→ 'instantiates a 3D bi-linearly sub-divided polar conic solid centered at the origin (0,0,0)'
S-P-CYLINDER : Generate 3D Sub-Divided-Polar-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided polar cylindrical solid centered at the origin (0,0,0)'
S-P-CYLICONE : Generate 3D Sub-Divided-Polar-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided polar conic-cylindrical solid centered at the origin (0,0,0)'
S-C-CAPSULE : Generate 3D Sub-Divided-Capped-Capsule
→ 'instantiates a 3D bi-linearly sub-divided flat-topped (capped) capsule solid centered at the origin (0,0,0)'
S-B-CUBE : Generate 3D Sub-Divided-Beveled-Cuboid
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) cuboidal solid'
S-B-CONE : Generate 3D Sub-Divided-Beveled-Cone
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) conic solid centered at the origin (0,0,0)'
S-B-CYLINDER : Generate 3D Sub-Divided-Beveled-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) cylinderical solid centered at the origin (0,0,0)'
S-B-CYLICONE : Generate 3D Sub-Divided-Beveled-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) conic-cylindrical solid centered at the origin (0,0,0)'
S-R-CUBE : Generate 3D Sub-Divided-Rounded-Cuboid
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edged) cuboidal solid'
S-R-CONE : Generate 3D Sub-Divided-Rounded-Cone
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edged) conic solid centered at the origin (0,0,0)'
S-R-CYLINDER : Generate 3D Sub-Divided-Rounded-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edged) cylindrical solid centered at the origin (0,0,0)'
S-R-CYLICONE : Generate 3D Sub-Divided-Rounded-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edged) conic-cylindrical solid centered at the origin (0,0,0)'
S-B-P-CONE : Generate 3D Sub-Divided-Beveled-Polar-Cone
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) polar conic solid centered at the origin (0,0,0)'
S-B-P-CYLINDER : Generate 3D Sub-Divided-Beveled-Polar-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) polar cylindrical solid centered at the origin (0,0,0)'
S-B-P-CYLICONE : Generate 3D Sub-Divided-Beveled-Polar-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided beveled (chamfered-edge) polar conic-cylindrical solid centered at the origin (0,0,0)'
S-R-P-CONE : Generate 3D Sub-Divided-Rounded-Polar-Cone
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edged) polar conic solid centered at the origin (0,0,0)'
S-R-P-CYLINDER : Generate 3D Sub-Divided-Rounded-Polar-Cylinder
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edge) polar cylindrical solid centered at the origin (0,0,0)'
S-R-P-CYLICONE : Generate 3D Sub-Divided-Rounded-Polar-Cylicone
→ 'instantiates a 3D bi-linearly sub-divided rounded (smooth-edge) polar conic-cylindrical solid centered at the origin (0,0,0)'

Generalised Cylinders

Figure 5.3: hierarchical map of the set of functions in qmsh that instantiate generalised-cylinders - to represent custom primitives based on extrusion, revolution and constrained sweep operations.
Extrusion Solids
EXTRSUION-XYZ : Generate 3D Linear-Extrusion-XYZ
→ 'instantiates a 3D data-driven linear-extrusion solid along a user-defined axis'
EXTRUSION-X : Generate 3D Linear-Extrusion-X
→ 'instantiates a 3D data-driven linear-extrusion solid along the X-axis'
EXTRUSION-Y : Generate 3D Linear-Extrusion-Y
→ 'instantiates a 3D data-driven linear-extrusion solid along the Y-axis'
EXTRUSION-Z : Generate 3D Linear-Extrusion-Z
→ 'instantiates a 3D data-driven linear-extrusion solid along the Z-axis'

Revolution Solids
REVOLUTION : Generate 3D Revolution
→ 'instantiates a 3D data-driven open-half-profile revolved solid about the Y-axis'
P-REVOLUTION : Generate 3D Polar-Revolution
→ 'instantiates a 3D data-driven polar open-half-profile revolved solid about the Y-axis'
TOROID : Generate 3D Toroid
→ 'instantiates a 3D data-driven cyclic-full-profile toroidal solid about the Y-axis'

Profile-Rail Solids
RAIL-XY : Generate 3D Cyclic-Profile-Rail-XY
→ 'instantiates a 3D data-driven cyclic profile-rail solid (a constrained generalised-cylinder) defined in the XY-plane'
RAIL-XZ : Generate 3D Cyclic-Profile-Rail-XZ
→ 'instantiates a 3D data-driven cyclic profile-rail solid (a constrained generalised-cylinder) defined in the XZ-plane'
RAIL-YZ : Generate 3D Cyclic-Profile-Rail-YZ
→ 'instantiates a 3D data-driven cyclic profile-rail solid (a constrained generalised-cylinder) defined in the YZ-plane'
O-RAIL-XY : Generate 3D Open-Profile-Rail-XY
→ 'instantiates a 3D data-driven open profile-rail solid (a constrained generalised-cylinder) defined in the XY-plane'
O-RAIL-XZ : Generate 3D Open-Profile-Rail-XZ
→ 'instantiates a 3D data-driven open profile-rail solid (a constrained generalised-cylinder) defined in the XZ-plane'
O-RAIL-YZ : Generate 3D Open-Profile-Rail-YZ
→ 'instantiates a 3D data-driven open profile-rail solid (a constrained generalised-cylinder) defined in the YZ-plane'

Symbolic Solids
CHARACTER-3D : Generate 3D Character-Symbol
→ 'instantiates a 3D symbolic (alpha-numeric) character solid'
B-CHARACTER-3D : Generate 3D Beveled-Character-Symbol
→ 'instantiates a 3D beveled (chamfered-edge) symbolic (alpha-numeric) character solid'
R-CHARACTER-3D : Generate 3D Rounded-Character-Symbol
→ 'instantiates a 3D rounded (smooth-edged) symbolic (alpha-numeric) character solid'
TEXT-3D : Generate 3D Character-Sequence
→ 'instantiates a 3D symbolic (alpha-numeric) compound character text-sequence solid'
B-TEXT-3D : Generate 3D Beveled-Character-Sequence
→ 'instantiates a 3D beveled (chamfered-edge) symbolic (alpha-numeric) compound character text-sequence solid'
R-TEXT-3D : Generate 3D Rounded-Character-Sequence
→ 'instantiates a 3D rounded (smooth-edged) symbolic (alpha-numeric) compound character text-sequence solid'

Transform Grammar



Figure 6.0: hierarchical map of the set of linear transformation functions exposed by qmsh.

Absolute Transforms

Figure 6.1: hierarchical map of the set of absolute (explicit) transform grammar operations in qmsh.
Absolute (Explicit) Euclidean Operators
T → TRANSLATE : Translate Entity
→ 'applies a translation linear transformation to an entity'
S → SCALE : Scale Entity
→ 'applies a scaling linear transformation to an entity'
R → ROTATE : Euler-Rotate Entity
→ 'applies a euler-rotation linear transformation about principal axes to an entity'
I → INVERT : Reflect Entity
→ 'scales an entity by a negative factor about principal axes and (conditionally) re-orients the entity such that the transformed entity possesses reflectional symmetry with its untransformed state - this is analogous to a mirroring transform'
MM → MATRIX-MULTIPLY : Entity Matrix-Multiplication
→ 'applies a general-purpose linear matrix-multiplication transformation to an entity'
Q → QUATERNION-ROTATE : Quaternion-Rotate Entity
→ 'applies a quaternion-rotation about a user-defined axis to an entity'

Relative Transforms

Figure 6.2: hierarchical map of the set of relative (implicit) transform grammar operations in qmsh.
Relative (Implicit) Euclidean Operators
C → CENTER : Center Entity About Origin
→ 'translates an entity such that the middle-position of its axis-aligned bounds coincides with the origin'
Z → ZERO : Entity Minimum-to-Origin
→ 'translates an entity based on its current axis-aligned bounds such that vertex coordinates are shifted to be positive with the minimum position coinciding with the origin'
NZ → NZERO : Entity Maximum-to-Origin
→ 'translates an entity based on its current axis-aligned bounds such that vertex coordinates are shifted to be negative with the maximum position coinciding with the origin'
W → WIDTH : Entity Scale-to-Match-Width
→ 'scales an entity uniformly about the origin based on the width of its current axis-aligned bounds to resize the entity'
H → HEIGHT : Entity Scale-to-Match-Height
→ 'scales an entity uniformly about the origin based on the height of its current axis-aligned bounds to resize the entity'
D → DEPTH : Entity Scale-to-Match-Depth
→ 'scales an entity uniformly about the origin based on the depth of its current axis-aligned bounds to resize the entity'

Instancing Operations



Figure 7.0: hierarchical map of the set of entity instancing functions exposed by the quick-mesh grammar for the purpose of coordinating generative operations involving structured repetition.
Instancing (Structured-Repetition) Operators
DUO : Duplicate-Entity
→ 'duplicates an entity - returning a new entity that can be modified independently of the source entity - the properties of the duplicated entity are deep-copied from the state of the target entity at the point of invocation'
L → AUTO-LINEAR : Automatic Linear-Sequence-Repeat
→ 'instances an entity linearly - i.e. about a line or an axis - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'
RING → AUTO-RADIAL-RING : Automatic Radial-Ring-Repeat
→ 'instances an entity radially - i.e. in a circular ring arrangement perpandicular to an axis - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'
G → AUTO-CARTESIAN-GRID : Automatic Cartesian-Grid-Repeat
→ 'instances an entity in a dense Cartesian grid - i.e. a uniform or non-uniform regularly-spaced matrix/cell arrangement - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'
INST → AUTO-GENERAL-INSTANCE : Automatic General-Instance-Repeat
→ 'instances an entity in a generalised arrangement - i.e. a custom user-defined layout - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'
SPI → AUTO-AXIS-SPIRAL : Automatic Axis-Spiral-Repeat
→ 'instances an entity in a spiral - i.e. a circular ring arrangement perpandicular to an axis, coupled with a fixed-length linear-offset (translational increment along the axis) for each - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'
BFLY → AUTO-BUTTERFLY : Automatic Butterfly-Repeat
→ 'instances an entity via a reflection - i.e. by duplicating and mirroring an entity along an axis to create a pair that possess reflectional symmetry - with automatic interaction testing to determine whether or not to perform a fast instance or a union instance'

Boolean-Logic Operations



Figure 8.0: hierarchical map of the set of boolean-logic (CSG) operators in the qmsh grammar.
Boolean-Logic Operators
+ → UNION : Boolean-Union (Addition: A+B)
→ 'computes the union of entities (such as the operands A and B) which is equivalent (analogous) to adding the entities together - i.e. the bitwise OR operation'
- → DIFFERENCE : Boolean-Difference (Subtract: A-B)
→ 'computes the difference of entities (such as the operands A and B) which is equivalent (analogous) to subtracting the right-hand operand from the left-hand operand'
& → INTERSECT : Boolean-Intersection (Intersect: A&B)
→ 'computes the intersection of entities (such as the operands A and B) which is equivalent (analogous) to isolating parts that are common to both left and right operands - i.e. the bitwise AND operation'
% → XOR : Boolean-Symmetric-Difference (Exclusive-Disjunct: A%B)
→ 'computes the exclusive-disjunction (symmetric-difference) of entities - which is equivalent (analogous) to isolating the parts that occur exclusively in each operand - i.e. the bitwise XOR operation'
! → COMPLEMENT : Unary-Complement (Negation: !A)
→ 'yields the complement of an entity - which maps loosely to negation or reversing orientation'

Colourisation



Figure 9.0: hierarchical map of the set of functions for entity colouring in the quick-mesh grammar.
Colourisation Functions
RGB : Red-Green-Blue Entity Colour
→ 'sets the diffuse colour components using a red-green-blue colour model'
RGBA : Red-Green-Blue-Alpha Entity Colour
→ 'sets the diffuse and transparent colour components using a red-green-blue colour model'
HSB : Hue-Saturation-Brightness Entity Colour
→ 'sets the diffuse colour components using a hue-saturation-brightness colour model'
HSBA : Hue-Saturation-Brightness-Alpha Entity Colour
→ 'sets the diffuse and transparent colour components using a hue-saturation-brightness colour model'
A → ALPHA : Entity Alpha-Transparency
→ 'sets the transparent colour components'

Constructions & Modifiers



Figure 10.0: hierarchical map of the key set of constructions and modifier operations in qmsh.
Constructions and Modifiers
CH → CONVEX-HULL : Construct Convex-Hull
→ 'computes the convex-hull of the vertices of a polygonal-shape (in two-dimensions) or a polyhedral-solid (in three-dimensions) - yielding a faceted entity'
GCH → GOURAUD-CONVEX-HULL : Construct Gouraud-Convex-Hull
→ 'computes the gouraud-convex-hull of the vertices of a polygonal-shape (in two-dimensions) or a polyhedral-solid (in three-dimensions) - yielding a continuous (smooth) entity'
TAP → TAPER : Taper-Along-Axis Deformation-Operator
→ 'applies a deformative tapering modification to an entity in an instantiative manner - i.e. yielding a distinct modified entity instance'
TWST → TWIST : Twist-About-Axis Deformation-Operator
→ 'applies a deformative twisting modification to an entity along a prinicipal axis in an instantiative manner - i.e. yielding a distinct modified entity instance'
SHR → SHEAR : Shear-Along-Axis Affine-Transform-Operator
→ 'applies an affine transform shearing modification to an entity in an instantiative manner - i.e. yielding a distinct modified entity instance'
NMM → NON-MANIFOLD-MERGE : Non-Manifold-Merge Utility-Operator
→ 'computes a non-manifold merge of a set of entities such that the topology of each entity in the input set is preserved in the output - i.e. this does not alter the arrangement or configuration of geometric elements and hence has the potential to yield a non-manifold set as output'

Measures & Queries



Figure 11.0: hierarchical map of the set of measurement functions in quick-mesh for querying entities.
Measures and Spatial Query Routines
MIN → MINIMUM : Calculate AABB-Minimum
→ 'computes the axis-aligned bounding-box minimum position of an entity'
MAX → MAXIMUM : Calculate AABB-Maximum
→ 'computes the axis-aligned bounding-box maximum position of an entity'
AVG → AVERAGE : Calculate Geometric-Mean
→ 'computes the geometric mean position of an entity'
MID → AABB-MIDDLE : Calculate AABB-Midpoint
→ 'computes the axis-aligned bounding-box middle position of an entity'
SPN → AABB-EXTENT : Calculate AABB-Span
→ 'computes the axis-aligned bounding-box extent or span of an entity along principal axis'
AREA : Calculate Surface-Area
→ 'computes the surface-area of an entity - in two or three dimensions'
VOLUME : Calculate Volume
→ 'computes the volume of an entity - in three dimensions'
PERIMETER : Calculate Perimeter
→ 'computes the perimeter-length of an entity - in two dimensions'

Utility Functions



Figure 12.0: hierarchical map of the set of auxiliary utility functions exposed by the qmsh grammar.

Trigonometric

Trigonometric Functions
SINE : Calculate Sine
→ 'returns the trigonometric sine of an angle specified in radians'
COSINE : Calculate Cosine
→ 'returns the trigonometric cosine of an angle specified in radians'
TANGENT : Calculate Tangent
→ 'returns the trigonometric tangent of an angle specified in radians'
ARC-SINE : Calculate Arc-Sine
→ 'returns an angle in radians representing the arc sine of a value'
ARC-COSINE : Calculate Arc-Cosine
→ 'returns an angle in radians representing the arc cosine of a value'
ARC-TANGENT : Calculate Arc-Tangent
→ 'returns an angle in radians representing the arc tangent of a value'

Numeric

Numeric Functions
ABSOLUTE : Absolute-Numeric-Value
→ 'returns the absolute value of a numeric entity - i.e. magnitude'
SQUARE-ROOT : Calculate Square-Root
→ 'returns the positive square root of a numeric entity as a decimal value'
CUBE-ROOT : Calculate Cube-Root
→ 'returns the cube root of a numeric entity as a decimal value'
SIGN : Sign-of-Numeric-Value
→ 'returns the result of applying the signum function to a numeric entity - i.e. 0 if the value equals zero, -1 if the value is less than zero and 1 if the value is greater than zero'
POWER : Calculate Numeric-Power
→ 'returns the result of raising a numeric entity to the power of another numeric entity'
LOGARITHM : Calculate Logarithm
→ 'returns the natural logarithm (base e) of a numeric entity'

Auxiliary: Entity Interrogation and Kernel Interaction

Auxiliary Utility Functions
PRINT : Print-Debugging-Statement
→ 'prints a user-specified message to a kernel's script-log for debugging purposes'
SIZE-OF : Calculate Size-of-Entity
→ 'computes the size of an entity in terms of the number of bytes required to represent the entity's current state - this is equivalent to the amount of memory an entity is currently consuming'
TYPE-OF : Determine Type-of-Entity
→ 'returns a utility structure denoting an entity's type for debugging purposes'
TO-STRING : Construct Entity-String-Representation
→ 'returns a textual string representation of an entity for debugging purposes'

Parametric Control



Figure 13.0: hierachical map of the classes of parametric control types supported by qmsh.
Un-Constrained Parameters
→ 'Control Parameters without Constraints'
Constrained Parameters
→ 'Control Parameters with Constraints'

Function Definition



User-defined functions enable the creation of re-usable generative modules and components, through encapsulation that also reduces repetition in scripts.

This section covers mechanisms in QMSH for flexibly defining new functions.

Primer: Actions versus Procedures
→ ''
Primer: Pre-Fix versus Post-Fix Definitions
→ ''

In QMSH there are four main classes of user-defined function. These are: pre-fix-user-actions, pre-fix-user-procedures, post-fix-user-actions and post-fix-user-procedures. Now whilst each of these classes of user-defined function is distinct (in terms of the invocation facilities they support), they share in common support for varying the level of abstraction (or generalisation) exhibited in their specifications (i.e. their signatures).

This abstraction varying mechanism underlies the concept of flexible function definition in QMSH in that it is the feature of the grammar that enables users to express both high-level (loosely-typed, pseudo-code-like) and lower-level (strong-statically-typed) function definitions. A nice way to rationalise this grammatical construct is as typing-discipline-agnostic function definition - and in QMSH this manifests as free, typed, bounded and hybrid user functions.

Free(dom) Functions
→ 'Abstract, High-Level, User-Defined Function Signatures'
Typed Functions
→ 'Conventional Statically-Typed User-Defined Function Signatures'
Bounded Functions
→ 'Input Argument Constrained User-Defined Function Signatures'
Hybrid Functions
→ 'Mixed Typing-Discipline User-Defined Function Signatures'
Nested Functions
→ 'Temporary User-Defined Functions Bound to an Operative-Scope'

To reiterate: QMSH's flexible-function-definitions manifest as free, typed and bounded user-operations - with additional grammatical support for hybrid and nested definitions. Together these mechanisms provide versatile options for defining custom generative routines and enable users of the grammar to easily extend the built-in functionality with custom geometric generators and modifiers.

Glossary



AAL: Automatic-Argument-Linearisation
AAP: Automatic-Action-Promotion
Absolute Transform
Action
AOS: Annonymous-Operative-Scope
Argument
Array
Automatic Return
Automatic Terminator
Axis-of-Revolution (Solid)
Boolean-Logic
Bounded Function
Comment
Constrained (Parameter)
Constructive-Solid-Modelling (CSG)
Cyclic (Shape)
D.O.I.E.O: Declaration-Order-IS-Execution-Order!
Entity
Exact Symbolic-Name Resolution
Executing Environment
Expression
FFI: Flexible-Function-Invocation
FFD: Flexible-Function-Definition
Fixed-Form (Solid)
Flexible-Functions
Flexible Symbolic-Name Resolution
Free(dom) Function
Function
Function Definition (Statement)
General Action (Statement)
Generalised-Cylinder
Generic Entity Array
Geometric Arithmetric Expression
Gouraud Shading
Hybrid Function
Immutable
Inline (Operation)
Instancing
Instantiative (Operation)
Kernel Directive (Statement)
Manifold
Mutable
Native (Symbol)
Object Assignment (Statement)
Open (Shape)
Operation
Operative-Scope
Operator
Parameter
Parameter-Definition (Statement)
Parametric-Control
PF-DN-SEC: Post-Fix Dot-Notation Sequential-Expression-Chain
Platonic (Solid)
Post-Fix (Construct)
Post-Fix Axis-Specifier
Post-Fix Exact-Angle-Specifier
Pre-Fix (Construct)
Pre-Fix Modifier-Symbol
Profile-Rail
Private (Symbol)
Procedure
Public (Symbol)
Relative Transform
Return (Statement)
Root (Geometry)
Script
SSE: Simple-Sequential-Expression
Statement
Symbol
Symbolic-Name
Symbolic-Operator
Temporary Entity
Typed Function
Typesafe Data Array
Un-Constrained (Parameter)
User-Defined (Symbol)
Variable
Variant (Geometry)
Volumetric
Zero-Argument Default-Return
Page End.