Coshape Customizers

# Main Project File

A customizer project is defined in YAML (opens new window) 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

# Material

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

# Shape

  • 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.

# Position

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.

# Rotation

The rotation uses ZYX Euler Angles in degrees (360 degrees equals full circle). The default value for position and rotation is 0.

# Scale

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).

# Parameters

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

# Expressions

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

← OpenJSCAD →