# Main Project File
A customizer project is defined in YAML and by default the compiler expects the data in a file at main.yml. It consists of a header section, an interface section and a component section.
# Header Section
The header section defines general properties that serve the purpose of documentation.
name: DS-1 Orbital Battle Station description: My awesome Death Star customizer! author: Galen Erso date_created: a long time ago
# Interface Section
The interface section defines the input variables of a customizer. Usually, these are numeric values with a lower and upper bound that are visualized as sliders in the graphical user frontend of the customizer.
To introduce a new variable, add a new, unique identifier (the name of the variable) to the interface section, e.g. 'length'. You are free to choose any name for your variable, just make sure it doesn't start with a number and doesn't contain any spaces. Note: Underscores in the variable name will be rendered as spaces in the graphical user frontend.
The input variable has a default value, which is defined with the value property. If the input should be a vaule range, the min, max and step properties define a linear scale.
To indicate the unit of the input variable in the graphical user frontend use the 'unit' property.
interface: length: min: 10 max: 200 step: 5 unit: inch value: 50 width: min: 10 max: 200 step: 5 unit: mm value: 40 height: min: 10 max: 200 step: 5 unit: mm value: 15
The corresponding graphical user frontend would look like this. [screenshot, UI prarameters]
# Components Section
The 'components' sections defines the individual parts of a customizer in terms of shape, material, transformation, cost and parameters.
A component's shape can be defined using a static mesh (STL) file or can be scripted. The script is OpenJSCAD and will be discussed in more detail in the next section of the tutorial. A scripted shape usually offers an interface of its own which is controlled by the parameter property. The Position and Rotation can be changed with the respective properties.
components: - base: material: type: pla color: rgb(1,1,1) shape: type: jscad file: base.jscad position: x: 0 y: 0 z: 0 rotation: x: 0 y: 0 z: 90 scale: x: 1 y: 1 z: 1 parameters: height: io.height width: io.width length: io.length radius: io.radius thickness: io.thickness
The material property serves the purpose of defining the look of the surface of a component in the graphical user frontend and documentation. The type property gives a hint for manufacturing and will be used to define material shaders at some point. The color property defines the color with red, green, blue and alpha channels ranging from 0 to 1.
rgb(1, 0, 0) // opaque red rgba(1, 0.5, 0, 0.25) // translucent orange
- type: STL, Jscad
- file: relative path from main.yaml
So far the compiler and customizer is able to process STL meshes and OpenJSCAD script files. There will be more formats at some point, depending on user requests.
The position is unit less, you can implicitly define all dimensions as millimeters or inches and apply the correct conversion when using the values from the interface variable.
The rotation uses ZYX Euler Angles in degrees (360 degrees equals full circle). The default value for position and rotation is 0.
The Scale is relative to the inital size of the component's shape and a value of 1 equals the inital size. The scale can be different in x,y and z. The default scale is 1.
Note that position, rotation and scale properties can be omitted, if the values are equal to the initial values, e.g. scale (1,1,1).
The parameter section applies values to the input variables of the OpenJSCAD script that defines the shape of the component. To access an interface variable, use the 'io' identifier on the right hand side of the assignment. On the left hand side you use the name of the variable that is being used in the shape script.
components: - base: shape: type: jscad file: base.jscad parameters: height: io.height width: io.width length: io.length radius: io.radius thickness: io.thickness
Note that the values assigned e.g. to the material color, position, rotation, scale or parameters can be expressions. The following is valid code.
... parameters: width: io.width - io.thickness ...
# Full main.yml example
interface: length: min: 10 max: 200 step: 5 unit: inch value: 50 width: min: 10 max: 200 step: 5 unit: mm value: 40 height: min: 10 max: 200 step: 5 unit: mm value: 15 radius: min: 1 max: 20 step: 1 unit: mm value: 3 thickness: min: 0.1 max: 10 step: 0.1 unit: mm value: 1.5 components: - base: material: type: pla color: rgb(1,1,1) shape: type: jscad file: base.jscad position: x: 0 y: 0 z: 0 rotation: x: 0 y: 0 z: 90 parameters: height: io.height width: io.width length: io.length radius: io.radius thickness: io.thickness - top: material: type: pla color: rgb(0,0,0.5) shape: type: jscad file: top.jscad position: x: 0 y: 0 z: io.height - io.thickness rotation: x: 0 y: 0 z: 90 scale: z: io.thickness parameters: width: io.width - io.thickness length: io.length - io.thickness radius: io.radius - io.thickness / 2