Notices
This section contains notices pertinent to mesh-makers.
Experimental Web-GL Support
Work is underway to bring Web-GL support to QMSH.
Presently this manifests as experimental support for emitting Web-GL compatible stand-alone static 3D entity-bundles.
Note: if you are using the command-line kernel you can try this out by adding the [-webgl] flag to your terminal invocations or makefiles. If you are using the mobile kernel you can simply select the stand-alone HTML or embeddable JSON options.
Positively: this provides a relatively portable means to quickly view the 3D entities you create on machines and devices that may not have a 3D-mesh viewer installed. It is also quite handy for quickly sharing ideas with fellow mesh-makers (i.e. you can send entities - that can be viewed directly in a browser - as email attachments without external dependencies).
Negatively: the current support is limited to statics only - meaning parametric control is not exposed in the auto-generated Web-GL entity bundles.
Investigations into supporting dynamic entities in Web-GL are on-going - however there is not a definitive timeline yet for inclusion.
In terms of the current development track: adding support for GLTF outputs and exposing/handling user-interaction in WebGL - are the immediate priorities.
Experimental Raspberry-Pi Support
Work is underway to bring QMSH to the Raspberry-Pi.
An experimental 32-bit build of the kernel for the Raspberry-Pi operating system is available on the project's homepage to enable researchers, engineers, educators and hobbyists to start playing with low-overhead purely-procedural polyhedral-programming on the popular single-board computer.
Note: that the 32-bit build has been tested on the Raspberry-Pi Model-2 and Model-4. It should also run on the Zero (albeit at a much slower pace) - however if you encounter any problems - send an email to: support@qmsh.org.
Positively: this provides a means to create moderately complex 3D entities directly on the Raspberry-Pi without the added overhead associated with running traditional interactive modelling packages with an OpenGL GUI. Additionally - if you use the Raspberry-Pi in educational contexts (for example to tutor students in practical computer-science) then you can now also introduce them to 3D procedural modelling using the Pi.
Negatively: although you can now script 3D entities on the Pi - presently the options for viewing, examining and interacting with your creations on the Pi are limited - relative to desktop or mobile use of the kernel. In particular: most open-source 3D packages that are capable of running on the Pi (i.e. FreeCAD, Blender...) that might otherwise function as general-purpose viewers, are noticeably slower (interaction-lag-wise) than their desktop equivalents.
Note: that to side-step the limited 3D-viewer options for the Pi - you can use the kernel's experimental Web-GL output to view your creations directly in the Pi's browser. However note that on older versions of the Pi there may be perceptible rendering and shading issues in the WebGL display. Additionally at HD resolution (i.e. 1920x1080) the Pi's framerate for WebGL interactions (rotating and zooming) drops significantly.
The current development track is focussed on addressing the limited viewing options that hinder/impair the usability of the kernel on the Pi.
Although initial experiments look positive - it is worth noting that the decision as to whether to promote the Raspberry-Pi to an officially supported target platform is yet to be made.
Experimental 3D Interchange-Format Support
Work is underway to extend the interoperability of the kernel's output geometries and their suitability to varying use-cases.
Practically this means experimental support for generating the following interchange formats has been added to the command-line kernel for beta testing. Simply add the corresponding flags to each kernel invocation command to test the output produced for each format.
-3mf → 3MF: 3D Manufacturing Format (Un-Compressed)
-amf → AMF: Additive Manufacturing Format (Un-Compressed)
-gts → GTS: GNU Tessellated Surfaces
-json → JSON: JavaScript Object Notation
-webgl → HTML: Standalone-WebGL-Bundle (html+css+js+glsl)
Note: that as experimentally supported output formats - the manner is which the kernel emits these 3D interchange files is subject to change - hence always double check the output.
Note: functionality is added regularly so check back for progress updates.
Issue-Tracker
This section lists known issues and corresponding work-arounds.
Kernel: Linux CPU-Architecture Support
Issue: only x86_64 binaries are presently available for the command-line kernel on Linux.
Resolution: currently - unless you have access to a machine that supports the x86_64 instruction set - you should use the command line kernel on Mac-OS or Windows operating systems.
Note: binaries for alternative CPU architectures (ia64, arm...) shall be added to the project's homepage in due course - subject to hardware availability and testing.
Additionally: investigations are on-going to establish the benefits, limitations and trade-offs inherent to alternative Linux distribution methods for the kernel's binaries. Essentially trials of Snap, Flatpak and AppImage are underway - however a firm decision is yet to be made. Presently AppImage is looking like the most suitable distribution method however this is subject to change.
Mobile-Editor: Tablet-Support
Issue: usability issues in the mobile-editor on tablets, chromebooks and similar devices.
Resolution: report any issues you encounter such that they can be fixed.
Note: although (in principle) the mobile-editor should function out-of-the-box on tablets (i.e. it has been designed to work agnostically independent of device type) - practically unfortunately (due to logistical hardware-access constraints) it has not yet been possible to perform thorough usability testing of the mobile-editor (for quality-assurance purposes) on such devices.
Official support for such devices shall be added incrementally - starting with 7-inch and 10-inch tablets. You can refer to the Google Play-Store listing for the mobile-editor for progress in this regard.
Mobile-Editor: Undo-Redo-Support
Issue: no undo-redo support in mobile-editor when writing scripts.
Resolution: be careful editing your scripts - for example rather than deleting a block of statements - simply comment them out instead. Additionally: remember to save your scripts! Alternatively - if undo-redo support is a must for you - then you can use the mobile-kernel with a third-party text-editor. If you opt for the external editor option - and the editor you choose to use supports source syntax-highlighting - then you can select C, C++ or Java language settings for your scripts.
Note: undo-redo support is in development.
Unity-Plugin: Missing Parametrics
Issue: the plugin for Unity does not (presently) expose inspector widgets to interactively modify the parameters defined in scripts - however the mobile-editor does.
Resolution: pending.
Note: parametric-control in the Unity-Editor (ahead-of-time) is in development - however it is unclear yet whether support shall be added for parametric-control in the Unity-Player (at runtime).
You can refer to the plugin's Unity Asset-Store listing for progress.
Kernel: Minimal-Vertex-Optimisation
Issue: minimal-vertex optimisation may fail for certain polyhedral arrangements in spite of their grammatical validity and structural and spatially coherence - typically manifesting as visible topological errors in an entity (such as a hole in a surface that should be manifold).
Resolution: presently you will have to modify your entity to avoid/side-step the troublesome elements of the arrangement - using your own awareness of the spatial relations amongst the components that define your entity. This is somewhat of an art - yet comes with practise. Often reducing a script's boolean-logic assembly complexity will be your first port of call in this regard.
Note: if you are sure that there are no subtle spatial oversight bugs in your script - then the error may be the result of a bug in the MVO routine. You can determine this by running the script as a basic-CSG-mesh (i.e. with no optimisation: -no_op). If the artefact is resolved (i.e. no longer manifests) as a product of the change in execution mode then it indicates an MVO bug - else it indicates an assembly error possibly resulting from the application of boolean-logic - or from a malformed entity.
Kernel: Non-Linear-Modifiers
Issue: applying certain non-linear modifiers (such as the twist operator) has the potential to induce unstable polyhedral arrangements - especially when applied to compound entities - which can spoil subsequent boolean-logic operations and minimal-vertex optimisation.
Resolution: pending.
Grammar: Automatic-Argument-Linearisation
Issue: automatic-argument-linearisation is only currently supported for the grammar's native (built-in) 2D and 3D geometry-generator functions.
Resolution: pending.
Note: AAL support for the grammar's remaining natives (transforms, instancers, utilities...) is in development. AAL for user-defined functions may take more time to mature.
Note: if you encounter an issue using the kernel or grammar that is not documented above, then you can report it by messaging: feedback@qmsh.org
If you need assistance working around these issues contact: support@qmsh.org
Questions & Answers
This section provides answers to questions related to QMSH.
What is Quick-Mesh?
A tool (a computer program) for creating 3D-mesh - or more precisely - a hardware, platform and framework agnostic general-purpose polyhedral procedural modelling kernel which exposes a high-level imperative geometric scripting language. Essentially Quick-Mesh provides a means to create geometric models using simple scripts. In-particular it strives to provide a standardised mechanism for the interchange of functional geometric descriptors. Quick-Mesh (.qmsh) also denotes the human-readable geometric file-format.
What is a Quick-Mesh Kernel?
Software that implements Quick-Mesh. Typically formed of a language-parser and a mesh-assembler.
What is the Quick-Mesh Grammar?
The high-level, imperative, entity-oriented, general-purpose scripting language that is used to define (specify the process of constructing) polyhedral mesh within Quick-Mesh. The grammar's principal syntactic construct is the post-fix, dot-notation, sequential-expression-chain (PF-DN-SEC).
What are the key limitations of Quick-Mesh?
QMSH is by design a purely-procedural kernel - meaning that the only way to describe a 3D entity is in a script. QMSH does not provide a back-door to mixed-procedural modelling wherein one couples automatically generated geometry with manually or interactively created geometry as is common in many pre-existing solutions. Whilst this brings numerous technical advantages - it can be both daunting and off-putting to some mesh-makers at first. Further the expressive scope of the QMSH grammar favours man-made structures and devices (that exhibit symmetry and structural-regularity) - more so than organic structures. In other words QMSH is not recommended for entities such as trees, plants or terrains. Additionally QMSH does not currently provide texture-mapping facilities.
Which platforms and environments are supported by Quick-Mesh?
Presently (as of V0): Android, Linux, Mac-OSX, Windows and Unity.
Which pre-existing languages influenced the Quick-Mesh Grammar?
Several. Firstly the C-family of programming languages (C, C++, C# and Java). Secondly higher-level languages such as Groovy, Python, Javascript. Thirdly domain-specific languages as LATEX and vitally prior procedural shape-grammars such as CGA-Shape, GML and Open-SCAD.
What differentiates Quick-Mesh from pre-existing shape-grammars?
QMSH's main distinguishing features are its simplicity, brevity and flexibility. You can download and run quick-mesh literally in minutes. There are no third-dependencies so setup is exceedingly easy. Furthermore - not only is the scripting-language designed to minimise symbolic-redundancy (whilst simultaneously increasing script legibility) - but the physical reference implementations also exhibit an unprecedented level of compactification relative to traditional 3D kernels and procedural modelling tools. This makes it possible to use QMSH in contexts and environments for which pre-existing systems and generative abstractions struggle - for example on low-power mobile devices and single-board computers. Further still - in spite of its simplicity the general-purpose nature of QMSH renders it a surprisingly versatile tool capable of expressing a wide range of highly varied entities - which vitally (and unlike typical CAD-system generated mesh) are suited to use in realtime systems such as games, interactive architectural visualisations, virtual environments and augmented reality applications.
How stable is the reference implementation of the Quick-Mesh Kernel?
Relatively stable. By and large it functions as expected - however certain aspects are being improved - in terms of robustness, computational efficiency and usability. Additionally some features - though originally planned for inclusion in the beta release - have been postponed and are being added incrementally. In short the kernel is a work in progress - but a functioning work in progress.
How much does registration as an industrial user cost?
Presently there is no charge to register as an industrial user of QMSH:V0 - however the process requires formal agreement to - and compliance with the terms of - Codemine's Industrial Partner Agreement. Crucially your organisation must be willing to indemnify Codemine against any legal and/or economic liability pertaining to and/or arising from your organisation's use of QMSH. This includes agreement to the restriction imposed preventing redistribution of QMSH's reference implementations and preventing its use in safely-critical systems and environments.
Does registration as an industrial user grant source-access?
No. Registration as an industrial user is (presently) largely a formality for organisations that must ensure their use of third-party software complies with Copyright and Intellectual-Property laws. However industrial registration also provides a means for organisations, enterprises and commercially inclined individuals to establish a formal channel of communication with Codemine. Note: whilst QMSH shall offer a free-to-use option perpetually - the cost of registration as an industrial user of future versions of QMSH is subject to change - specifically inflation in line with the logistical cost associated with provisioning for industrial users.
Does registration as an industrial user grant redistribution-rights?
Generally - no. However under certain circumstances - Codemine may (solely at its own discretion) authorise certain parties to redistribute specific tools. Note: this does not in any way affect your rights to redistribute the original content (scripts and models) that you create using QMSH under the terms you deem appropriate (FOSS or proprietary). If you are interested in integrating QMSH into an application or system you are developing and wish to discuss this matter further contact Codemine: support@codemine-ind.co.uk.
Why is redistribution currently forbidden?
Primarily - safety. Essentially QMSH is in beta - meaning that whilst it may be safe to use it directly - as long as one is present to visually check and verify the output mesh - it may not be safe to bundle the kernel into commercial applications for which the polyhedra generated may not have been verified ahead-of-time on all potential target devices and platforms. Such stability shall come over time as the kernel matures and undergoes wider scale testing by a larger array of mesh-makers. Whilst one might argue that a mere warning or disclaimer of liability might suffice - instead, in order to guard against any potential, indirect or incidental legal culpability, a uniform no-redistribution policy has been adopted to simplify the matter. In short: it would not be wise nor prudent to encourage embedding or bundling the kernel in commercial and industrial applications at present given that it is in active development. Therefore the terms of use forbid any form of unauthorised resale or redistribution of the reference implementations such that there is no doubt or ambiguity.
When will redistributable versions of Quick-Mesh be available?
In due course. As the kernel develops - redistribution options shall be added for industrial users - potentially for a fee. Note: there is not a definitive timeline for the transition to permissible industrial redistribution of the reference implementations. However if it becomes apparent that such options are in high demand amongst industrial users then coordinating the transition shall be prioritised.
Which aspects of Quick-Mesh are non-procedural?
None! QMSH's ethos is pure proceduralism! Note: this extends beyond the kernel and grammar. Every aspect of Quick-Mesh is effected procedurally.
Note: if you can not find the answer to a question you have - get in touch.
For general enquiries message: info@qmsh.org
For technical queries message: support@qmsh.org