qmsh
All Rights Reserved. © Codemine-Ind. → Last Updated: 2024-02-25
beta
V0 (beta)

QMSH

→ the proceduralite's modelling kernel


Overview



Quick-Mesh (QMSH or qmsh) is a simple, general-purpose procedural-modelling kernel with a high-level imperative geometric scripting language. Quick-Mesh aims to be intuitive (easy-to-use), concise (short and sweet) and flexible (interoperable).

You can use Quick-Mesh as a simple stand-alone scripted CAD system to generate 3D models (polyhedral-mesh). You can also use Quick-Mesh within your own programs and applications as a cross-platform geometric modelling library.

Quick-Mesh scripts are human-readable plain text files stored with the file extension .qmsh. Each QMSH kernel evaluates input scripts and outputs (generates) 3D mesh which can be stored as OBJ, PLY, OFF or STL files. Figure 1.1 provides examples of simple models written in the Quick-Mesh scripting language to help clarify.


Figure 1.1: simple examples of 3D models (rendered above) written in the quick-mesh scripting language (see the .qmsh files below) to help contextualise the input and output of the kernel.

cube_minus_sphere.qmsh
{↓}
1: return cube - sphere.s(1.25); 

cube_octahedron.qmsh
{↓}
1: o = octahedron; 
2: return cube - o.duo.s(1.5) & o.s(2.0); 

dual_band_ring.qmsh
{↓}
1: return torus(0.01,0.001,64,32).sy(3) 
2:   - torus(0.011,0.00025,64,16).ly(2,0.00125).cy; 

t_junction_pipe.qmsh
{↓}
1: return cylinder(0.25,0.5,32).zy 
2:   + cylinder(0.25,1,32).rz(90) 
3:   - cylinder(0.2,0.5,32).zy 
4:   - cylinder(0.2,1,32).rz(90); 

mechanical_part.qmsh
{↓}
1: m = cylinder.s(0.5,3,0.5); 
2: return cube + m - m.duo.rz(90) - m.duo.rx(90); 

wooden_dinner_chair.qmsh
{↓}
1: return cube(1.05,0.1,1.05) 
2:   + cube(0.125,1,0.125).nzy.grid(2,1,2,0.9,0,0.9).cxz 
3:   + cube(0.8,0.1,0.1).tz(0.45).ringy(4).nzy.ty(-0.05).ly(2,-0.75) 
4:   + cube(0.125,1.25,0.125).zy.lx(2,0.9).cx.tz(-0.45) 
5:   + cube(1.05,0.1,0.15).t(0,1.25,-0.45) 
6:   + cube(0.8,0.075,0.075).ty(0.25).ly(4,0.25).tz(-0.45); 


Each QMSH script contains a set of statements - which specify modelling operations that define a boundary-representation (a polygon-mesh) of an object. In this manner each script encodes the modelling process (i.e. the set of steps) required to define a mesh rather than the actual geometric elements (vertices/edges/faces). In simple words: each script is an intermediary representation (IR).

QMSH kernels perform two basic operations to create models from scripts: language-parsing (parsing for short) and geometric-assembly (also termed mesh-assembly or simply assembly). Figure 1.2 illustrates the behaviour described.

Input
a plain text file with extension .qmsh
→
Process : QMSH
1 parse → statements in input
2 assemble → output mesh
→
Output
a 3D model file as:
.obj, .off, .ply or .stl

Figure 1.2: simple schematic illustrating the general operation of a quick-mesh kernel.


The primary aims, objectives and underlying motivations of QMSH are outlined next.

→
Intuitive
scripts should be easy to read, write, automatically generate and parse - essentially the grammar should be simple to understand, highly legible and quick for one to learn.
→
Concise
the kernel and scripting language should be succinct - in particular the build-size of the kernel's executables should be small and the grammar exposed should exhibit brevity - more precisely: the objective is to minimise symbolic redundancy in geometric scripts.
→
Flexible
in terms of its interoperability with pre-existing work-flows, in its ability to construct highly-varied geometric forms and in the versatility of its grammatical constructs.
→
Efficient
from a computational perspective and from a user-workflow perspective - in particular the requirement for a light-weight streamlined architecture that is suited to use in realtime systems, especially on low-power embedded devices (such as mobiles) under strict memory constraints, and offering a fast and fluid modelling iteration cycle for end-users.
→
Robust
to geometric degeneracy and topological artefacts (*up to the limit of double-precision floating-point arithmetic) - in particular stable, reliable (dependable) execution, with consistent meshing results across all supported platforms and device types.
→
Procedural
to its core - in the purest sense of the term - or more plainly fully-automatic, without the reliance on manual interactive editing or non-procedural external assets - capable of expressing all necessary modelling operations functionally - pure proceduralism.


In terms of access: QMSH may be used for free for non-commercial purposes (including research, education and similar not-for-profit endeavours). QMSH may also be used within commercial contexts subject to industrial registration which is available through Codemine. For more information refer to the Terms-of-Use.

Geometric Features



Modelling Techniques, Components and Classes of Operation

→
Geometric Primitive Library
a suite of parameterised mesh generating functions - the kernel's native-geometries:

→
Generalised-Cylinders (3D-Sweeps/Profile-Rails)
data-driven procedures for creating custom primitives using various types of generalised-cylinder - including extrusions, revolutions, toroids, sweeps and profile-rails:
→
Euclidean Transformations
functions for linear transformations: translating, scaling and rotating geometry - in-particular a short-hand notation for absolute (explicit) and relative (implicit) transforms:

Absolute (Explicit) Transforms
Translate: T(x,y,z), TX(x), TY(y), TZ(z)...
Scale: S(x,y,z), S(f), SX(x), SY(y), SZ(z)...
Rotate: RX(x), RY(y), RZ(z)...
Relative (Implicit) Transforms
Center: C(), CX(), CY(), CZ()...
Zero (To-Origin): Z(), ZX(), ZY(), ZZ()...
Negative-Zero: NZ(), NZX(), NZY(), NZZ()...
→
Instancing Operations (Structured Repetition)
functions for generating regular and semi-regular patterns - such as linear, Cartesian grid and radial arrangements - vitally these helpers reduce the need for iterative loops:

→
Boolean-Logic Operations (Constructive Modelling)
set-theoretic operations for creating seemingly complex objects as the product of composing simpler primitives - union, difference, intersection and symmetric-difference:

→
Parametric Control
extended numeric and literal types to represent attributed external control parameters - which enable platform and environment agnostic automatic user-interface generation:

1: DBL x(2,0,8,"X-Scale-Factor"); 
2: DBL y(4,0,8,"Y-Scale-Factor"); 

↓ ↓ ↓

DBL
DBL
X-Scale-Factor
Y-Scale-Factor
2.0
4.0

→
Colourisation
functions for altering the colours of geometric elements to delineate object components:
→
Modifications, Constructions and Utility-Routines
non-linear manipulations, deformations and geometric constructions (such as hulls and envelopes), predicates and measures, debugging and profiling functions:



Technical Details: Geometric Facilities and Build Properties

In terms of the lower-level technical details of the geometric behaviour and mesh attributes supported by the kernel, QMSH also offers the following:

→
Support for N-Gon (General-Polygon) Mesh
including triangle, quadrilateral, uniform-topology and mixed-topology polygon mesh.
→
Support for Mesh Smoothing-Groups
enables sharp crease/ridge edges to be combined with smooth continuous surfaces.
→
Support for Per-Vertex Analytic RGB-Colour
(for mesh debugging) colour-by: normal, valence, declaration-order, operand-id, group-id.
→
Support for Topology-Preserving Minimal-Vertex CSG Operations
suitability to low-polygon-count modelling in resource constrained environments.
→
Support for Parallel Assembly
multi-core simultaneous processing for scalable assembly of larger arrangements.

QMSH runs natively on Linux, Mac-OS and Windows operating systems. QMSH also runs natively on Android mobile devices and as a plugin for the Unity-Engine.

The kernel's pre-built binaries occupy roughly 3.0 MB for each OS. They are distributed as standalone executables - which simply means they do not require installation in order to be run, and that there are no third-party dependencies.

Scripting Language



six_sided_dice.qmsh
{↓}
 1: c = cube & sphere(32,16).s(1.4); 
 2: d = sphere(16,8).s(0.2,0.05,0.2).rgb(0.25); 
 3: z1 = d.duo.ty(0.5); 
 4: z2 = d.lx(2,0.4).cx.ry(45).ty(0.5).rz(90); 
 5: z3 = d.duo.tz(0.2).ringy(3).ty(0.5).rx(90); 
 6: z4 = d.duo.tz(0.2).ringy(4).ty(0.5).rz(-90); 
 7: z5 = d.duo + d.gridxz(2,2,0.4,0.4).cxz; 
 8: z5.ty(0.5).rx(-90); 
 9: z6 = d.duo.tz(0.25).ringy(6).ty(-0.5); 
10: return c - z1 - z2 - z3 - z4 - z5 - z6; 

Figure 3.1: a simple script illustrating the use of the qmsh grammar (left) to define a dice (right).


Quick-Mesh’s scripting language aims foremost to be intuitive, concise and flexible.

It derives some of its constructs and semantics from the C-family of programming languages (C, C++, C# and Java) and some from scripting languages such as Javascript, Python and Groovy. Quick-Mesh also introduces a number of original syntactic constructs and grammatical conventions that seek to reduce the number of characters one must type in geometric modelling scripts - whilst simultaneously enhancing legibility and ease of understanding. In essence the Quick-Mesh scripting language is designed to be short and sweet. Further more (as a consequence of this), it is vital to note that Quick-Mesh is not intended to be a general purpose Turing complete programming language. Instead - it seeks only to provide the core (fundamental/axiomatic) facilities for the scripted definition of geometric objects.

Formally the QMSH Scripting Language can be classified as an imperative, closed-form, high-level, object-oriented, procedural geometric DSL - whose primary grammatical construct is the sequential-expression-chain effected with dot-notation semantics. It employs a declaration-order execution-model over bracketed expressions (or precedence-based symbolic operators) and though being strongly typed internally emulates the behaviour of a dynamically typed interpreted grammar.

The next sections provide a quick tour of the key aspects of the QMSH grammar.


Statement Types

Put simply - a statement instructs a kernel's geometric assembler to do something.

There are four key types of statement supported by the scripting language which are outlined in figure 3.2 and in the following break-down for reference.

types_of_statement.qmsh
{↓}
1: // a parameter-definition statement 
2: INT count(4,1,5,"Repeat-Count"); 
3: // an object-assignment statement 
4: o = octahedron.lx(count,1); 
5: // a general-action statement 
6: o.cx.rgb(0,0.5,1); 
7: // the return statement 
8: return o; 

Figure 3.2: a simple script illustrating the four key types of statement provided by the scripting language for controlling the behaviour of a quick-mesh kernel.

→
Parameter-Definition Statements
declare and define public (external) control parameters that drive the modelling process.
→
Object-Assignment Statements
assign private (internal) objects to symbols - these are temporary intermediary objects.
→
General-Action Statements
invoke operations (that preserve referential integrity) on private (internal) objects.
→
The Return Statement
specifies which object should be the output of the modelling process (the return value).

All statements are terminated by a semicolon (;), and C-style comments (i.e. // for single lines and /* ... */ for multiple lines) may be used to communicate the geometric intent of statements for clarity. Statements can span multiple lines and/or multiple (short) statements can occur on the same line. Note: the only mandatory type of statement in a quick-mesh script is the return statement - all others are optional.


Syntax, Constructs and Language Usability Features

The key concepts, constructs and syntactic sweeteners in the QMSH grammar, that enhance the brevity and legibility of its geometric scripts, are outlined next.

✓
Implicitly
Typed
Variables
✓
Geometric
Arithmetic
Operators
✓
Interactive
Control
Parameters
✓
DOIEO:
Declaration-
Order-IS-
Execution-Order
✓
PF-DN-SECs:
Method-Chaining
(on Steroids)
✓
Pre-Fix
Modifier-
Symbols
✓
Post-Fix
Axis-Specifiers
(Swizzling)
✓
FSR:
Flexible-Symbol-
Resolution
✓
Native
Synonyms
(Aliases)
✓
Inline
Operations
✓
Instantiative
Operations
✓
AOS:
Annonymous-
Operative-
Scopes
✓
IIRR: Immediate-
Intermediary-
Resource-
Release
✓
Flexible
Functions
(FFI + FFD)
✓
FFI: Flexible
Function
Invocation
✓
FFD: Flexible
Function
Definition
✓
AAP:
Automatic
Action
Promotion
!
AAL:
Automatic
Argument
Linearisation
✓
auto-return
✓
auto-terminator
✓
Generic
Entity-Arrays
!
Typesafe Data-Arrays
✓
Kernel
Directives
✓
Free(dom)
Functions
✓
Typed
Functions
✓
Bounded
Functions
✓
Hybrid
Functions
✓
Nested
Functions

Independently each of these language constructs is incredibly simple - both from a conceptual viewpoint and from the practical perspective of actually implementing them. Indeed when considered in isolation each has limited utility. Yet when one combines these notational devices - under the banner of a geometric DSL - their cumulative power out-weighs the mere summation of their parts. In-particular they reduce the complexity and length of procedural modelling scripts relative to pre-existing languages. To help clarify the following examples indicate the relative decrease in code complexity and script length facilitated by the QMSH grammar.


Comparing Languages: OpenSCAD to Quick-Mesh


Figure 3.3: examples of simple models defined procedurally - illustrating (from left to right): sphere_minus_cylinders, bandstand and openscad_legacy_example003.


The first example (sphere_minus_cylinders - see figure 3.4) indicates the benefits of an imperative grammar relative to a declarative grammar in terms of the former's ability to simplify script syntax. Note: in particular the linearity of the imperative approach relative to the tree-like structure of the declarative approach.

Open-SCAD
(.scad)
 1: module sphere_minus_cylinders() { 
 2:   N = 16; // 32, 64, 96, 128, 192 
 3:   difference() { 
 4:     $fn = N; 
 5:     sphere(6); 
 6:     cube(9, center=true); 
 7:     cylinder(h=20, r=2, center=true); 
 8:     rotate([90,0,0]) cylinder(h=20, r=2, center=true); 
 9:     rotate([0,90,0]) cylinder(h=20, r=2, center=true); 
10:   } 
11: } sphere_minus_cylinders(); 
Quick-Mesh
(.qmsh)
 1: N = 16; // 32, 64, 96, 128, 192 
 2: return sphere(N,N/2).s(12) 
 3:   - cube.s(9) 
 4:   - cylinder(2,20,N) 
 5:   - cylinder(2,20,N).rx(90) 
 6:   - cylinder(2,20,N).rz(90); 
 7:    
 8:    
 9:    
10:    
11:    

Figure 3.4: comparing Open-SCAD's (left) and QMSH's (right) grammar


The next example (bandstand - see figure 3.5) indicates the advantages of qmsh's instancing (structured repetition) routines - in coordinating common tasks such as constructing a polar arrangement. Note: (in particular) the manner in which the vertical columns are defined in Open-SCAD (lines 9-12) and in QMSH (lines 3-4).

Open-SCAD
(.scad)
 1: module bandstand() { 
 2:   $fn = 32; 
 3:   translate([0,0,-120]) { 
 4:     difference() { 
 5:       cylinder(h=50, r=100); 
 6:       translate([0,0,10]) cylinder(h=50, r=90); 
 7:       translate([100,0,35]) cube(50,center); 
 8:     } 
 9:     for (i = [0:5]) { 
10:       translate([sin(360*i/6)*80, 
11:         cos(360*i/6)*80,0]) 
12:         cylinder(h=200, r=10); 
13:     } 
14:     translate([0,0,200]) 
15:       cylinder(h=80, r1=120, r2=0); 
16:   } 
17: } bandstand(); 
Quick-Mesh
(.qmsh)
 1: N = 32; 
 2: b = cylinder(100,50,N).zy; 
 3: c = cylinder(10,200,N) 
 4:     .zy.tx(80).ringy(6); 
 5: h = cylinder(90,50,N).zy.ty(10) 
 6:   + cube(50,50,100).zyz.ty(10); 
 7: r = cone(120,80,N).zy.ty(200); 
 8: return b - h + c + r; 
 9:    
10:    
11:    
12:    
13:    
14:    
15:    
16:    
17:    

Figure 3.5: syntactic comparison: bandstand model expressed in Open-SCAD's grammar (left) and in QMSH's grammar (right)


The last comparative example (openscad_legacy_example003 - fig. 3.6) demonstrates the effect that qmsh's syntactic constructs (for minimising symbolic redundancy) have in primitive instantiation and in boolean logic operations.

Open-SCAD
(.scad)
 1: module openscad_legacy_example003() { 
 2:   difference() { 
 3:     union() { 
 4:       cube([30,30,30], center=true); 
 5:       cube([40,15,15], center=true); 
 6:       cube([15,40,15], center=true); 
 7:       cube([15,15,40], center=true); 
 8:     } 
 9:     union() { 
10:       cube([50,10,10], center=true); 
11:       cube([10,50,10], center=true); 
12:       cube([10,10,50], center=true); 
13:     } 
14:   } 
15: } openscad_legacy_example003(); 
Quick-Mesh
(.qmsh)
 1: a = cube(30) 
 2:   + cube(40,15,15) 
 3:   + cube(15,40,15) 
 4:   + cube(15,15,40) 
 5:     ; 
 6: b = cube(50,10,10) 
 7:   + cube(10,50,10) 
 8:   + cube(10,10,50) 
 9:     ; 
10: return a - b; 
11:    
12:    
13:    
14:    
15:    

Figure 3.6: comparing Open-SCAD's (left) and QMSH's (right) grammar


***

These simple examples should provide an overall sense of the appearance of scripts written in the Quick-Mesh grammar - relative to a venerable pre-existing grammar.


Parallelism in Quick-Mesh

The quick-mesh scripting-language also provides first-class support for constructs enabling more advanced use-cases - prominent amongst which is the grammar's simple, portable, task-level parallel-execution-model - outlined next.

✓
#parallel;
Parallel-Assembly
Kernel-Directive
✓
Parallel
Return
Statement
✓
Parallel
Element
Definitions
✓
(optional)
Parallel Globals
[ Prefix | Suffix ]
✓
Sequential
(Mono-Core)
Execution
✓
Simultaneous
(Multi-Core)
Execution
✓
Re-Assembly
Culling
✓
Parallel
Parameter
Definitions
✓
Invocation
Grouping
(Batching)
✓
Inline
Parallel
Returns
✓
CCPP:
Constant-Cost
Parallel-Prefix
✓
Monolith
& Modular
Exporters
!
OOC:
Out-of-Core
Parallel-Write
✓
Quantifying
Parallel
Overhead
✓
Quantifying
Parallel
Efficiency
!
Cluster
Compute

The kernel and grammar's support for parallelism extends the expressive scope of the language and helps expedite the assembly of larger scenes and arrangements by enabling the distribution of work across multiple executors or processing-cores.

Parallelism also contributes to the long-term viability of the kernel and grammar as it enables improvements in hardware to map directly to increased performance for more challenging (larger or complex) geometric arrangements. In simpler terms the ability to describe and run concurrent assemblies easily means that as computers get faster (i.e. the typical number of CPU and compute cores increases) parallel-scripts also get faster without any requirement for revision by the mesh-maker.

Though there are some caveats and constraints - the core idea is that out-of-the-box support for parallel-assembly imbues the scripting-language with scalability and (as a pleasant by-product) a measure of pain-free performance future-proofing.

Getting Started



Getting Started with the QMSH-Editor on Android
  1. Read the Terms-of-Use
  2. Download the QMSH-Editor (see download section)
  3. Ensure the App has been Granted the Device Storage-Permission
  4. Open the App and Explore...

    Note: on some Android devices an application restart may be required after granting the storage permission (i.e. close the app and then re-launch it) in order for the permission change to fully take effect.
Getting Started with the QMSH-Kernel on Linux, Mac-OS and Windows
  1. Read the Terms-of-Use
  2. Download the QMSH-Kernel (see download section)
  3. Un-Zip the Downloaded File
  4. Navigate (in your Terminal/Console) to the Un-Zip Location
  5. Ensure the Kernel-Binary is Executable
  6. Test the Kernel:
    Linux & Mac-OS: 
./qmsh -tess -rgb -nxyz -obj example_scripts/six_sided_dice.qmsh 
Windows:
qmsh.exe -tess -rgb -nxyz -obj example_scripts\six_sided_dice.qmsh
  7. View the Output Mesh (using your preferred 3D-application)
  8. Read the Accompanying PDF Documentation and Explore...
Getting Started with the QMSH-Inspector on Linux, Mac-OS and Windows
  1. Read the Terms-of-Use
  2. Download the QMSH-Entity-Inspector (see download section)
  3. Un-Zip the Downloaded File
  4. Navigate (in your Finder/File-Browser) to the Un-Zip Location
  5. Launch QMSH-EI or QMSH-EI.exe
  6. Set the Start-Up Configuration and Select OK to Proceed
  7. Open a Quick-Mesh Script-File (.qmsh)
  8. Inspect the Assembled Entity's Mesh Interactively
  9. Read the Accompanying Notes and Explore...

    Note: the entity-inspector depends upon the command-line kernel therefore remember to also download the kernel for your platform beforehand.
Getting Started with the QMSH-Plugin for Unity
  1. Read the Terms-of-Use
  2. Download the QMSH-Plugin (on the Unity Asset-Store)
  3. Create a New Unity Project (as you normally would)
  4. Add the QMSH-Plugin to the Newly Created Project's Assets
  5. Configure the QMSH-Plugin to use an instance of the QMSH-Kernel
  6. Test the Plugin: Open the Example Scenes and Run
  7. Read the Accompanying PDF Documentation and Explore...

Video Tutorials

▶
→ Introduction to the Quick-Mesh Command-Line Kernel
A tutorial demonstrating command-line use of the quick-mesh kernel.
Keywords: QMSH-Kernel

▶
→ Introduction to the Quick-Mesh Engine-Plugin: Unity
A tutorial explaining the use of the quick-mesh plugin in Unity.
Keywords: QMSH-Plugin, Unity

▶
→ Introduction to the Quick-Mesh Web-Sandbox
A tutorial covering the experimental quick-mesh web-assembly editor.
Keywords: QMSH-Sandbox

Download



The Quick-Mesh Kernel is available in a number of forms:

Note: ensure you have read and understood the Terms-of-Use before downloading.

Mobile-Editor

Quick-Mesh's Mobile-Editor is a free-to-use stand-alone application that exposes the kernel's runtime geometric scripting language in the form of a sand-boxed IDE (integrated development environment): which includes components for script-editing, parsing and mesh-assembly, rendering and visualisation, documentation and IO.


Figure 4.1: screenshots of the qmsh mobile-editor running on android - depicting (from left to right): the procedural-editor (the app's main input component), the geometry-viewer (for visualising and debugging the output mesh), the app's embedded documentation and the options and settings control.

This self-contained system defines an end-to-end work-flow for scripted procedural mesh creation that is intuitive and accessible to all. If you are new to procedural modelling or want to try QMSH quickly, without commitment, and without a steep learning curve, then the Mobile-Editor is the best place to start.


Use the link above to download the mobile-editor's latest release APK V:0.2.5.

To find out more about the mobile-editor and to browse related mobile applications in the eco-system - see the quick-mesh tool-repository - which provides more in-depth information including technical details, supplementary media and release notes.

→ QMSH Tool-Repository

The quick-mesh tool-repository aims to simplify access to the complete suite of quick-mesh applications - offering a privacy-friendly distribution channel that places fellow mesh-makers in control of if, when and how application updates are applied.

Note: an earlier version of the mobile-editor (V:0.1.7) is also available via Google Play - however in light of recent changes in Play-Store policy it is unclear at present as to when an updated version of the editor shall appear on the Play-Store.

QMSH Editor
for Android
Available on Google Play
 OPEN →


Note: ensure you have read and understood the Terms-of-Use before downloading.

Desktop-Kernel

Quick-Mesh's Desktop-Kernel is a free-to-use stand-alone, cross-platform, command-line program that implements the geometric scripting language defined by QMSH. Written in C++, these lower-level tools provide reference implementations of the QMSH kernel for developers, technicians and engineers that can be invoked as any system process - either directly from the command-line or from within user-written programs using standard system calls. Note: the desktop kernel does not have a graphical user-interface - it is essentially a geometric compiler.




An experimental build of the command-line kernel compatible with the Raspberry-Pi operating system - is also provided for educators, researchers and engineers.


Additionally - a universal build of the quick-mesh kernel for Android is provided to simplify use of the grammar with an external editor on machines and devices for which terminal access and command-line invocation are generally prohibited. Note: the universal Android build includes a minimalistic user-interface for the kernel.



Note: ensure you have read and understood the Terms-of-Use before downloading.

Entity-Inspector

Quick-Mesh's Entity-Inspector is a free-to-use interactive graphical front-end to the command-line kernel that provides facilities similar to the mobile-editor for desktop platforms. The entity-inspector aims to simplify the use of the kernel whilst simultaneously exposing support for grammar-centric features that are not directly accessible at the command-line (such as interactive parametric-control).


Figure 4.2: screenshot of the qmsh entity-inspector running on mac-osx - depicting the six-sided-dice example entity's surface, interactively rendered in 3D in the app's simple, minimal user-interface.

Note: that unlike the mobile-editor the entity-inspector (purposefully) does not include a script-editing component. This is largely to enable you to use your text-editor of choice when meshing on a desktop or workstation. Essentially this tool acts as a simple, minimalistic, dedicated qmsh-entity viewer that manages invoking the kernel on your behalf and displaying the resulting 3D mesh for you to examine and explore. Note: that the entity-inspector depends on the command-line kernel.




An experimental build of the entity-inspector compatible with the Raspberry-Pi operating system - is also provided for educators, researchers and engineers.



Note: ensure you have read and understood the Terms-of-Use before downloading.

Engine-Plugin

Quick-Mesh's Engine-Plugin is a free-to-use interoperable framework-agnostic extension module that enables evaluation of the QMSH grammar within pre-existing digital-content-creation systems and engines. Each plugin automates the process of converting the mesh generated by the kernel into framework-friendly structures. Note: the engine plugins depend on the command-line desktop kernel.

QMSH Plugin
for Blender
Distributed by Codemine
(release pending...)
...

QMSH Plugin
for Unity
Available on the Asset Store
 OPEN →

QMSH Plugin
for Unreal
...
...


Note: ensure you have read and understood the Terms-of-Use before downloading.

Note: the Android robot icon is a trademark of Google - the Linux Tux icon is a trademark of Linus Torvalds - Mac-OS and the Finder icon are trademarks of Apple - Windows and the Windows icon are trademarks of Microsoft - Raspberry-Pi and the Raspberry-Pi icon are trademarks of the Raspberry-Pi Foundation - Unity-Engine and the Unity icon are trademarks of Unity-Technologies - Unreal and the Unreal icon are trademarks of Epic - the Blender icon is a trademark of the Blender Foundation.

For help getting started with these tools refer to the corresponding documentation.

Documentation



The following links provide access to the kernel's PDF documentation:

Note: ensure you have read and understood the Terms-of-Use before downloading.


→
Mobile-Editor : Quick-Start Guide
Instructions explaining the use of the mobile-editor - this guide documents the components and behaviour of the app's user-interface - and is visually orientated with figures and diagrams to support comprehension. Note: that the app provides in-depth embedded documentation that also covers the functions in the scripting language.
Mobile-Editor-Guide
new users
3.6 MB
A4
PDF
→
Scripting Language : Quick-Look Summary-Sheet
A conference-style A1 reference poster (as 2 side-by-side A2 posters) that summarises the geometric grammar defined by QMSH - this is designed to help new users quickly become acquainted/conversant with the key functions in the scripting language.
Language-Summary
new users
5.5 MB
A2
PDF
→
Desktop-Kernel : Quick-Start Guide
Instructions explaining the use of the desktop-kernel - this guide specifies the supported command-line options for controlling the operation of the kernel's assembler - with clarifying examples of invocation from the terminal and from within user-programs (via system-calls). Note: this is a technical guide for advanced users - and does not cover the basics of the scripting language - readers should already be familiar with the grammar.
Desktop-Kernel-Guide
advanced users
0.8 MB
A4
PDF
→
Engine-Plugin : Quick-Start Guide
Instructions explaining the use of the engine-plugin - this guide deals with the process of invoking the kernel from within frameworks and engines both ahead-of-time (offline - i.e. at build/compile/design time) and dynamically at runtime. Note: again that this is a technical guide targeted at advanced users and does not cover the basics of the geometric grammar - readers are expected to be familiar with the kernel.
Engine-Plugin-Guide
advanced users
2.9 MB
A4
PDF


Note: ensure you have read and understood the Terms-of-Use before downloading.


Additionally: an online version of the public-working-draft of the user reference manual for the quick-mesh scripting language is available via the following link.

→
Language Reference
an online version of the reference manual for the quick-mesh grammar.
→ Language-Reference--

Note also that the periodically updated QMSH Video Documentation Repository includes tutorial videos and application previews to assist new mesh-makers.

Example Scripts



The following examples demonstrate simple 3D entities expressed in the quick-mesh scripting language. Select an image to display the corresponding script.


Example-Script: 'axis_tubes_intersect.qmsh'
axis_tubes_intersect.qmsh



axis_tubes_intersect.qmsh
{↓}
1: f = cylinder(0.25,2,32) 
2:   - cylinder(0.2,2,32); 
3: return f & f.duo.rx(90); 
Example-Script: 'linear_repeat_detail_tube.qmsh'
linear_repeat_detail_tube.qmsh



linear_repeat_detail_tube.qmsh
{↓}
1: c = cylinder(0.5,5,32); 
2: d = torus(0.5,0.125,32,16).ly(11,0.5).cy; 
3: e = cylinder(0.25,5.25,32); 
4: return c - d - e; 
Example-Script: 'doorstop.qmsh'
doorstop.qmsh



doorstop.qmsh
{↓}
1: clip = cube.sz(0.25) 
2:   + cylinder.s(0.25,1,0.25).tx(-0.5); 
3: slant = wedge.zy.s(1.25,0.5,0.25).tx(-0.25) 
4:   + cube.nzy.s(1.25,0.05,0.25).tx(-0.25); 
5: hole = cylinder.s(0.2,1,0.2).tx(-0.5); 
6: ret = clip & slant - hole; 
7: return ret.sy(0.5).cxyz; 
Example-Script: 'sphere_axis_discs.qmsh'
sphere_axis_discs.qmsh



sphere_axis_discs.qmsh
{↓}
1: c = cube(1.5,0.05,1.5).ly(3,0.125).cy; 
2: return c + c.duo.rx(90) + c.duo.rz(90) 
3:   & sphere(1.25) + sphere; 
Example-Script: 'abstract_energy_capsule.qmsh'
abstract_energy_capsule.qmsh



abstract_energy_capsule.qmsh
{↓}
1: r = capsule(0.25,2,32,16).rgb(0.5,0.525,0.55) 
2:   + cylinder(0.275,0.125,32).ly(4,0.5).cy.rgb(0.25) 
3:   - capsule(0.125,1,32,16).sx(0.2).tx(0.25) 
4:     .ringy(4).rgb(0.85,0.875,0.9); 
5: c = cone(0.05,0.5,16).zy.t(0.25,0.875,0) 
6:     .ringy(8).ry(360.0/16).rgb(0.5,0.75,1); 
7: return r - c - c.duo.rz(180); 
Example-Script: 'mechanical_gear_A.qmsh'
mechanical_gear_A.qmsh



mechanical_gear_A.qmsh
{↓}
 1: c = cylinder(1,0.1,32); 
 2: t = torus(1,0.05,32,16); 
 3: m = c+t; 
 4: i = cylinder.s(0.5).tz(1.025).ringy(8); 
 5: o = cylinder.s(0.25).tz(0.5) 
 6:     .ry(180.0/8).ringy(8); 
 7: b = cube(0.5,1,0.05).tx(-0.5) 
 8:     .ry(180.0/8).ringy(8); 
 9: h = cylinder(0.25,1,8); 
10: return m - i - o - b - h; 
Example-Script: 'mechanical_gear_B.qmsh'
mechanical_gear_B.qmsh



mechanical_gear_B.qmsh
{↓}
 1: a = sphere.s(10,0.5,10).rgb(0.5,0.55,0.6); 
 2: s = sphere(16,8).s(1.5); 
 3: b = s.duo.tZ(5).ringY(16).rgb(0,0.5,1); 
 4: c = s.duo.tZ(2.25).ringY(8).rgb(0,0.5,1); 
 5: d = cone(16).s(0.5).rX(180).rgb(0.5) 
 6:     .t(0,0.25,3.5).ringY(16); 
 7: e = cone(8).s(0.5).rX(180).rgb(0.5,0,1) 
 8:     .t(0,0.25,1.25).ringY(8); 
 9: f = torus(3.5,0.125,32,8).tY(0.25).rgb(1); 
10: g = torus(1,0.125,16,4).tY(0.25).rgb(1); 
11: return a - b - c - d - e - f - g; 
Example-Script: 'short_table.qmsh'
short_table.qmsh



short_table.qmsh
{↓}
1: b = 0.0025; 
2: legs = bcube(0.05,0.425,0.05,b).zy.grid(2,1,2,0.5,0,0.5).cxz; 
3: top = bcube(0.555,0.05,0.555,b).zy.ty(0.4); 
4: table = top + legs; 
5: return table; 
Example-Script: 'swivel_chair.qmsh'
swivel_chair.qmsh



swivel_chair.qmsh
{↓}
 1: c = cylinder(0.5,1,32) 
 2:   - cylinder(0.45,1,32) 
 3:   - cylinder(0.8,1,32).rz(90).t(0,0.5,0.5) 
 4:   + sphere.s(0.9,0.25,0.9).ty(-0.3) 
 5:   + cylinder(0.45,0.05,32).ty(-0.5) 
 6:   - cube(0.6,0.05,1).ly(5,0.1) 
 7:   + cylinder(0.1,0.5,32).ty(-0.75) 
 8:   + cylinder(0.2,0.1,32).ty(-1) 
 9:   + capsule(0.05,0.5,16,8).rx(90).zz 
10:     .rx(-10).tz(0.1).ty(-1).ry(36).ringy(5); 
11: return c.cy; 
Example-Script: 'simple_block_sofa.qmsh'
simple_block_sofa.qmsh



simple_block_sofa.qmsh
{↓}
1: b = 0.025; 
2: c = bcube(0.25,0.5,0.75,b).lx(2,1.75+0.25).cx.zy 
3:   + bcube(1.75,0.75,0.25,b).zy.ty(-0.075).rx(-10).t(0,0.25,0.25) 
4:   + bcube(1.75,0.25,0.75,b).zy; 
5: return c; 
Example-Script: 'media_stand.qmsh'
media_stand.qmsh



media_stand.qmsh
{↓}
1: b = 0.0025; 
2: horizontals = bcube(0.9,0.02,0.18,b).zy.grid(1,6,1,0,0.2125,0).ty(0.2125); 
3: verticals = bcube(0.02,1.5,0.185,b).zy.grid(4,1,1,0.3,0,0).cx; 
4: base = bcube(0.925,0.02,0.25,b).zy.tz(0.03); 
5: top = bcube(0.925,0.02,0.19,b).zy.ty(7*0.2125); 
6: stand = base + verticals + horizontals + top; 
7: return stand.rgb(1,0.95,0.9).cy; 
Example-Script: 'floor_standing_speaker.qmsh'
floor_standing_speaker.qmsh



floor_standing_speaker.qmsh
{↓}
1: c = cube(0.2,1,0.2).zy; 
2: b = cube(0.18,0.98,0.02).t(0,0.5,-0.1); 
3: o = sphere(32,4).rx(90).s(0.15,0.15,0.02).ly(5,0.19).cy.t(0,0.5,0.1); 
4: t = torus(0.075,0.005,32,8).rx(90).ly(5,0.19).cy.t(0,0.5,0.1); 
5: n = sphere.s(0.05,0.01,0.05).rx(90).ly(5,0.19).cy.t(0,0.5,0.09); 
6: ret = c - o - b + t + n; 
7: return ret.cy; 
Example-Script: 'mini_sub_woofer.qmsh'
mini_sub_woofer.qmsh



mini_sub_woofer.qmsh
{↓}
1: c = cube(0.15,0.3,0.4); 
2: d = cylinder(0.125,0.01,32) 
3:   + sphere.s(0.25,0.01,0.25).ty(-0.005); 
4: d.rz(90).tx(0.075); 
5: e = sphere.s(0.1).t(0,-0.075,0.2); 
6: f = torus(0.05,0.005,32,16).rx(90).t(0,-0.075,0.2); 
7: g = cube(0.13,0.28,0.02).tz(-0.2); 
8: return c - e + d + f - g; 
Example-Script: 'usb_pen_drive.qmsh'
usb_pen_drive.qmsh



usb_pen_drive.qmsh
{↓}
 1: c = cube(0.06,0.01,0.025) 
 2:   - cube(0.01,0.01,0.01).t(-0.025,0,0.0075) 
 3:   - cube(0.01,0.01,0.01).t(0.025,0,-0.0075) 
 4:   + cylinder(0.01,0.01,32).t(-0.02,0,0.0025) 
 5:   + cylinder(0.01,0.01,32).t(0.02,0,-0.0025) 
 6:   & capsule(0.01125,1,32,1).rz(90) 
 7:   - cube(0.03,0.008,0.005).tz(0.0125); 
 8: h = capsule(0.00375,0.02,32,16).rz(90).s(0.5,1,0.5).tz(0.01); 
 9: h.tx(0.0075).rgb(0.75,0.25,0.25); 
10: e = cylinder(0.001,1,4).rz(90).tz(-0.012).lz(2,0.024) 
11:   + cylinder(0.00025,1,4).rx(90).tx(-0.03).lx(2,0.06); 
12: t = torus(0.01,0.00025,32,4) 
13:   & cube.zx.nzz; 
14: t.t(0.02,0,-0.0025); 
15: t = t + t.duo.ry(180); 
16: u = cube(0.0025,0.005,0.012).tx(0.03); 
17: p = cube(0.02,0.004,0.011).tx(0.03) 
18:   - cube(0.02,0.0035,0.0105).tx(0.03) 
19:   + cube(0.019,0.00125,0.0105).t(0.03,-0.00125,0).rgb(0.25,0.5,0.75) 
20:   - cube(0.002,0.005,0.002).lz(2,0.005).cz.t(0.035,0.0025,0) 
21:   + cube(0.0175,0.00025,0.00125).t(0.03,-0.000675,0) 
22:     .rgb(1,0.75,0.5).lz(4,0.0025).cz; 
23: c.rgb(0.25); 
24: e.rgb(0.5); 
25: t.rgb(0.5); 
26: u.rgb(0.375); 
27: ret = c - e - t - u + h + p; 
28: return ret; 
Example-Script: 'cylindrical_light_shade.qmsh'
cylindrical_light_shade.qmsh



cylindrical_light_shade.qmsh
{↓}
 1: c = torus(0.2,0.0025,64,8).ly(2,0.25).cy; 
 2: t = cylinder(0.0025,0.16,8).rx(90).zz.tz(0.04).ringy(3) 
 3:   + cylinder(0.04,0.005,64) 
 4:   - cylinder(0.02,0.005,64); 
 5: t.ty(0.1275); 
 6: s = cylinder(0.201,0.25,64) 
 7:   - cylinder(0.199,0.25,64); 
 8: s.rgba(0,0.5,1,0.5); 
 9: // s.rgba(1,0.25,0.25,0.5); 
10: return c + t + s; 
Example-Script: 'low_watt_light_bulb.qmsh'
low_watt_light_bulb.qmsh



low_watt_light_bulb.qmsh
{↓}
 1: c = cylinder(0.025,0.02,32) 
 2:   - torus(0.025,0.001,32,4).ty(-0.01) 
 3:   - torus(0.025,0.0005,32,4).ty(-0.005) 
 4:   + sphere(32,16).s(0.05,0.025,0.05).ty(0.01) 
 5:   + cylicone(0.015,0.01,0.01,32).ty(0.0225) 
 6:   - torus(0.015,0.005,32,32).ty(0.02575) 
 7:   + cylicone(0.01,0.0075,0.02,32).ty(0.0275) 
 8:   + capsule(0.001,0.02,8,4).rx(90).ty(0.035) 
 9:   - torus(0.0075,0.001,32,8).ty(0.0375) 
10:   + sphere(16,8).s(0.008,0.001,0.004) 
11:     .ty(0.0375).lz(2,0.006).cz; 
12: h = cylinder(0.005,0.01,32) 
13:   + torus(0.005,0.0005,32,4).ty(-0.005); 
14: hs = h.duo.nzy.lx(2,0.0125).cx.tz(0.0125); 
15: hs = hs.ringy(3); 
16: p = cylinder(0.004,0.07,32); 
17: ps = p.duo.nzy.lx(2,0.0125).cx.tz(0.0125); 
18: ps = ps.ringy(3); 
19: r = torus(0.00625,0.004,32,32).rx(90) 
20:   & cube.nzy; 
21: rs = r.duo.t(0,-0.07,0.0125).ringy(3); 
22: ret = c - hs + ps + rs; 
23: return ret.cy; 
Example-Script: 'rotary_dial.qmsh'
rotary_dial.qmsh



rotary_dial.qmsh
{↓}
1: s = sphere(64,32).sy(0.5) 
2:   - cube(0.02,0.1,0.02).tz(0.5).rx(20).sy(0.5).ringy(16).rgb(0.25) 
3:   - sphere(8,2).s(0.025,0.1,0.025).tz(0.5).rx(45).sy(0.5).rgb(0.25); 
4: b = cube(5,5,5).nzy; 
5: h = s.duo.rx(180).zy.ty(0.0125); 
6: k = s & sphere(64,32).s(0.25,1,0.875); 
7: return s - h + k - b; 
Example-Script: 'championship_ring.qmsh'
championship_ring.qmsh



championship_ring.qmsh
{↓}
 1: a = cylinder(0.5,1,64).rx(90) 
 2:   + cube(1,2,1).zy; 
 3: c = cylinder(0.5,1,64) 
 4:   & a 
 5:   - cylinder(0.475,1,64).rx(90) 
 6:   - cube.nzy.zz.tz(0.155) 
 7:   - cube.nzy.nzz.tz(-0.155); 
 8: t = cube.zy 
 9:   & sphere(64,32).s(0.95).sy(0.25); 
10: t.ty(0.5).rgb(0.25); 
11: c.rgb(1,0.8,0.5); 
12: return c + t; 


For further examples refer to the accompanying PDF collection: 28 QMSH Scripts.

→
28 QMSH Scripts
a collection of 256 free-to-use example qmsh scripts written by the language's author in order to help elucidate the subtleties of the grammar.
→ 28 QMSH Scripts--


To keep up to date with the latest developments in the suite of examples - refer to the supplementary mobile compendium: The Quick-Mesh Script Collection.

QMSH Script
Collection
Distributed by Codemine
(re-release pending...)
...

Note: the script collection is a 'living-document' in the sense it is updated in sync with the kernel so to reflect the emerging constructs available to fellow mesh-makers.


Note: ensure you have read and understood the Terms-of-Use before downloading.

Contact & Support



For general enquiries address emails to: info@qmsh.org

For technical support using QMSH address emails to: support@qmsh.org

To report bugs, issues, request new features and/or suggest geometric, grammatical or usability improvements address emails to: feedback@qmsh.org

To report errors in this document address emails to: errata@qmsh.org

Terms-of-Use



The terms and conditions that govern the use of the Quick-Mesh Kernel, Scripting-Language and the associated tools and resources are summarised below.

→
Quick-Mesh is provided AS IS - WITHOUT ANY WARRANTY.
→
Quick-Mesh is Free-to-Use for Non-Commercial and Not-for-Profit Endeavours.
→
Quick-Mesh may also be used within Commercial-Contexts subject to Registration as an Industrial-User through Codemine-Industrial-Software.
→
Quick-Mesh is NOT Open-Source-Software - it is Closed-Source Software.
→
Quick-Mesh may NOT be used in Safety-Critical-Contexts.
→
Quick-Mesh may NOT be used to Facilitate Criminal or Terrorist Activity.

The terms and conditions related to the rights to appropriate intellectual property largely conform to the view that 'one-has-rights-to-the-things-one-creates'.

In terms of Codemine's rights to QMSH:

→
Quick-Mesh's Kernels', Editors' and Inspectors' Physical Implementations Remain the Exclusive Property of K. Edum-Fotwe and Codemine-Industrial-Software.
→
Unauthorised Redistribution or Resale of Quick-Mesh is Strictly Prohibited and May Incur Liability to Criminal Prosecution and/or Civil Claims for Damages.
→
Codemine-Industrial-Software Retain All Intellectual Property Rights Pertaining to the Implementation of the Quick-Mesh Kernel, Editor, Inspector and Tool-Chain.
→
Codemine-Industrial-Software Retain All Intellectual Property Rights Pertaining to the Formal Definition of the Quick-Mesh Scripting-Language.
→
Codemine-Industrial-Software Retain All Intellectual Property Rights Pertaining to the Production, Maintenance and Distribution of Quick-Mesh's Documentation.

In terms of an end-user's rights to content (scripts and models):

→
End-Users Retain All Intellectual Property Rights Pertaining to the Novel Content (Scripts and Models) that they Create using Quick-Mesh.
→
End-Users Accept Legal and Economic Responsibility for Ensuring their Use of Quick-Mesh Does Not Infringe upon the IP Rights of Third-Parties.

In terms of end-users' responsibilities towards one another:

→
End-Users Agree to be Respectful and Courteous towards other End-Users.
→
End-Users Agree to Act Fairly and in a Non-Discriminatory Manner towards other End-Users in Matters Pertaining to the Distribution, Commercialisation or General Monetisation of Content Created using Quick-Mesh.

Privacy Policy

The privacy policy applicable to Quick-Mesh online is simple - and is the same as the privacy policy applicable to all of Codemine's online sites and services.

In order to protect the personal information of users - Codemine does not track, monitor nor record any information enabling the identification of individual users. Codemine's policy is strictly Cookie-Free, Tracker-Free, Ad-Free and Spam-Free.

→
Codemine operates a Cookie-Free policy for all of its online content. Essentially Codemine does not use browser technologies such as cookies.
→
Codemine does not engage in the distribution of unsolicited mail for any reason.
→
If you choose to contact Codemine by email (for example to report a bug or an issue, or to provide feedback or request a new feature, or for technical support), your message will be handled by Codemine's mail system. Codemine uses ProtonMail as its mail system - therefore emails to Codemine are also subject to the privacy considerations and behavioural constraints stated in Proton's Terms-of-Service.
→
Whilst Codemine's direct online offerings are cookie-free, tracker-free, ad-free and spam-free - be aware that accessing content created by Codemine which is available through third-party distribution channels will result in behaviour outside of Codemine's control. As concrete examples of this: the QMSH-Editor's (currently deprecated) Google Play-Store listing and the QMSH-Plugin's Unity Asset-Store listing will result in cookies served by Google and Unity-Technologies, their affiliates and partners.

Tools & Resources



→
Community Forum
auxiliary resources for users of qmsh - including: questions and answers, trouble-shooting tips, debugging guides, an issue-tracker and project development notes.
→ Community Forum--
→
Researcher Resources
lower-level tools for engineers and researchers - to facilitate experimentation with - and integration of - the grammar and generative kernel exposed by QMSH.
→ Researcher Resources--
→
Sandboxed Web-Editor
an experimental client-side browser-based sandboxed IDE for the qmsh grammar - with basic script editing and mesh assembly features - designed to make it easier to try quick-mesh safely and without having to install additional software.
→ Sandboxed Web-Editor--
→
Entity Exchange
an experimental client-side browser-based direct-share system for quick-mesh 3D procedural entities - to simplify entity exchange and exposition amongst mesh-makers.
→ Entity Exchange--(opens a new tab)
→
Tool Repository
canonical tool repository for the quick-mesh kernel and grammar - to simplify access options for mesh-makers - including binaries, release-notes and supporting media.
→ Tool Repository--

Page End.