Customization parameters format

[hrgdavor]

Top level object

Integrations would extract their parameter definitions and convert them to this format so UI can be displayed.

Attributes of the main document

• title - title for the script
• parameters - list of [Parameter|Group] (defined in Group and Parameter section)
• presets - a list of preset combinations of values for the parameters, so author can provide interesting combinations as additional showcase of the script posibilities
  definition for groups is yet to be decided

Preset

• name - name of the parameter combination
• values - object with key:value to fill the customizer

Group

This is a special type of parameter that defines a group of inputs that is usualy expandable in the UI to reduce the clutter when there is a long list of parameters.

• type="group"
• caption - caption for the group
• hint - longer descriptive info about the group (like ? tooltip)
• initial - [open|closed]

for now, there is no hierarchy defined structurally (like a children property). If one of the parameters is a group those after it are part of that group

Parameter

Format for single parameter.

list of attributes

This is a list of attributes that define a parameter, but not all are used for every parameter type

Bare minimum

• type - actual data type UI should return, and also used to decide on default UI
• initial - initial value (also used to reset the form)
• name - name of the parameter used in the script

Minumum to support enums (select box)

• options - a list of values for enum can be and array of enum values, or object that is interpreted {enumValue:enumLabel}

A label with more descriptive name of the parameter and a hint/tooltip

• caption - Displayed name in the IU (name is used as fallback)
• hint - longer descriptive info about the parameter (like ? tooltip)

Extended options for different types of input elements

• min - for numerical types
• max - for numerical types
• step - for numerical types
• decimals - number of decimals for floating point numbers (int implies 0 decimals)
• maxLength - maximum length for string type
• input - author can use this hint to ask for different UI (slider for numbers)

Extension for optional UI elements that only make sense if another parameter has specific value (this could be done without dependsOn by defining it structurally, so the depending parameters are children in the document structure). For example, a model for a box, where you have a parameter checkbox that decides if a hole is drilled in the box. And if it is unchecked, it would be nice to hide "holeDiameter" parameter

• dependsOn - name of parameter that this one depends on
• dependsValue - value of dependsOn that makes this parameter visible

attribute: type

...

supported types

• number - integral number or floating point number (like float or double, those will not be distinguished here)
• string - textual value
• boolean -

supported inputs

the very basic minimum inputs to implement and support most of the parameters. These are recognized by type or if values list is present.

• input - default for int,string,decimal. Textual input box that could impose some constraints depending on type
• checkbox - for booleans
• select - for enums (if parameter defines values atrribute)

Extended inputs that allow for a bit different user experience. These are activated with input attribute.

• radio - instead of select when smaller number of options makes it nicer to use
• range - a range slider for numbers
• color - a color picker
• date - very low priority, and with questionable utility

[jmwright]

Where will this attribute information live? Will it just be in the CadHub database, or will it be attached to the model script somehow?

[Irev-Dev]

I saw this was discussed on discord already which I haven't read through properly so might be a might be repeating things have already been said. But essentially the attribute information will live as part of the script in the case of openSCAD in special comments and JSCAD, in for a particular export of the script. So no need to attach it in anywhere. If we start saving presets of these values, in that case we will attach it somehow but I think I want to get multi-files working in the ide before we try and solve that.

[Irev-Dev]

Thanks @hrgdavor, very comprehensive.

I like the 'depends on' concept. 👍

I don't like the enums been represented by an array of values and labels separately, I think it makes for an awkward authoring experience. Essentially it's a list of key-values I think and object makes more sense. Although would be happy to support both an object or an array for strings in case you don't want to have separate labels for the strings-types.

{
  numName1: 1,
  numName2: 2,
}

{
  strName1: 'str1',
  strName2: 'str2',
}

[
  'str1',
  'str2',
]

To make sure I was thinking about it correctly I wrote demo code, but really it was mostly typescript types, I'm still struggling with the difference between int and decimal and I think that we should just have a number type that automatically becomes an int if the step and initial value is divisible by one.

The following snippets are here https://github.com/Irev-Dev/cadhub/blob/kurt/cadhub-customizer-test-code-437/app/web/src/components/Customizer/customizerConverter.ts

So here is my implementation of types for Hrg's work above. At this point I'm only supporting number strings and booleans, and I'm not implemented anything for groups, input parameter, or any type of select/enum to begin with.

type CadhubTypeNames = 'int' | 'decimal' | 'string' | 'boolean'

interface CadhubParamBase {
  type: CadhubTypeNames
  caption: string
  name: string
}
interface CadhubStringParam extends CadhubParamBase {
  type: 'string'
  initial: string
  placeholder?: string
  maxLength?: number
}
interface CadhubBooleanParam extends CadhubParamBase {
  type: 'boolean'
  initial?: boolean
}
interface CadhubNumberBase extends CadhubParamBase {
  initial: number
  min?: number
  max?: number
  step?: number
}
interface CadhubDecimalParam extends CadhubNumberBase {
  type: 'decimal'
  decimal?: number
}
interface CadhubIntParam extends CadhubNumberBase {
  type: 'int'
}

type CadhubParams = CadhubStringParam | CadhubBooleanParam | CadhubDecimalParam | CadhubIntParam

Likewise the following is an example of typing for JSCAD with an example convert function, with example input output for a subset of Params

// JSCAD
type JscadTypeNames = 'group' | 'text' | 'int' | 'number' | 'slider' | 'email' | 'password' | 'date' | 'url' | 'checkbox' | 'color' | 'choice' | 'radio'

interface JscadParamBase {
  type: JscadTypeNames
  caption: string
  name: string
}
interface JscadGroupParam extends JscadParamBase {
  type: 'group'
  initial?: 'open' | 'closed'
}
interface JscadTextParam extends JscadParamBase {
  type: 'text'
  initial: string
  placeholder: string
  size: number
  maxLength: number
}
interface JscadIntNumberSliderParam extends JscadParamBase {
  type: 'int' | 'number' | 'slider'
  initial: number
  min?: number
  max?: number
  step?: number
}
interface JscadDateParam extends JscadParamBase {
  type: 'date'
  initial: string
  min: string
  max: string
  placeholder: string
}
interface JscadEmailPasswordColorParam extends JscadParamBase {
  type: 'email' | 'password' | 'color'
  initial: string
}
interface JscadUrlParam extends JscadParamBase {
  type: 'url'
  initial: string
  maxLength: number
  size: number
  placeholder: string
}
interface JscadCheckboxParam extends JscadParamBase {
  type: 'checkbox'
  checked: boolean
  initial: boolean
}
interface JscadChoiceRadioParam extends JscadParamBase {
  type: 'choice' | 'radio'
  initial: number | string
  values: (string | number)[]
  captions?: string[]
}

type JsCadParams = JscadGroupParam | JscadTextParam | JscadIntNumberSliderParam | JscadDateParam | JscadEmailPasswordColorParam | JscadUrlParam | JscadCheckboxParam | JscadChoiceRadioParam


jsCadToCadhubParams([
  { type:'slider', name:'length', initial:340, caption:'Length', min:210, max:1500},
  { name: 'text', type: 'text', initial: '', size: 20, maxLength: 20, caption: 'Plain Text:', placeholder: '20 characters' },
  { name: 'int', type: 'int', initial: 20, min: 1, max: 100, step: 1, caption: 'Integer:' },
  { name: 'number', type: 'number', initial: 2.0, min: 1.0, max: 10.0, step: 0.1, caption: 'Number:' },
  { name: 'date', type: 'date', initial: '2020-01-01', min: '2020-01-01', max: '2030-12-31', caption: 'Date:', placeholder: 'YYYY-MM-DD' },
  { name: 'checkbox', type: 'checkbox', checked: true, initial: true, caption: 'Checkbox:' },
])

function jsCadToCadhubParams(input: JsCadParams[]): CadhubParams[] {
  // do some magic
  return [
    { type: 'decimal', name:'length', initial:340, caption:'Length', min:210, max:1500},
    { name: 'text', type: 'string', initial: '', maxLength: 20, caption: 'Plain Text:', placeholder: '20 characters' },
    { name: 'int', type: 'int', initial: 20, min: 1, max: 100, step: 1, caption: 'Integer:' },
    { name: 'number', type: 'decimal', initial: 2.0, min: 1.0, max: 10.0, step: 0.1, caption: 'Number:' },
    { name: 'date', type: 'string', initial: '2020-01-01', caption: 'Date:', placeholder: 'YYYY-MM-DD' },
    { name: 'checkbox', type: 'boolean', initial: true, caption: 'Checkbox:' },
  ]
}

For the OpenSCAD meta data output, I think it should all be able to fit into what's been outlined above, so I put together a little example openscad/openscad#3801. Although it's neglecting groups and that the reports for the time being.

[hrgdavor]

I don't like the enums been represented by an array of values and labels separately

I agree, and we can use single property options that can be

• an object where key if value, and value is label for UI
• array of strings or numbers

Although in object syntax keys will not be numbers but strings, it is not a problem for jscad customizer, it can just internally convert a string into a number if param should be a number.

Also regarding int versus number distinction, I completely agree if you want to just have number type that it should be like that in CadHub ... If this is relevant to a jscad script then jscad integration can easily cleanup the values returned by UI.

I have changed the description to match these 2 changes

[Irev-Dev]

Sweet, thanks @hrgdavor.

[hrgdavor]

added section for presets. I like this idea, and have been thinking about it for a while. Sby else mentioned this, so I decided it is worth defining here.

Preset

• name - name of the parameter combination
• values - object with key:value to fill the customizer

[Irev-Dev]

Thats something we can do entirely in the Cadhub side since it just equates to saving values and feeding them back in on render.

[hrgdavor]

Well, as script author this is something I would like to define in/along the script. There was such feature request in jscad forums (no official git issue yet)

But if you decide to support it only as CadHub feature, I would not mind too much.
jscad does not have a mechanism to provide anything but parameter definitions yet.

It is a nice thing to have with script anyway, so it is worth doing one way or another.

[Irev-Dev]

Yup something to think about, we can probably do both where the script takes priority, but the author can save a number presets though the UI.

[hrgdavor]

Likely CadHub will have this before integrations support it in scripts, but if/when integration also provides the presets, they could be combined in the UI.... but any such design decision is better done when the time comes.

[impermaxvict]

Hey everyone, to me it seems as if a lot of effort is invested in a customizer.
Since this project is about Code-CAD after all, which means customization is just a change of a variable away, I was wondering about the value a customizer offers.
In my opinion, it is kind of unnecessary/redundant since one could just change a value in the code.
What do you think?

[Irev-Dev]

Code driven CAD is the "Most" parametric form of CAD since the author can add what ever logic is needed to make sure the parts can deal with a huge range of values, the customizer gives a way for others who maybe are not familiar with coding the ability to modify parts to suit their need, i.e. its for non-programmers mostly.

[hrgdavor]

For me personally it is integral to the making of models even for myself. In many cases I find it more conveniet to test the model via customizer than changing variables.
I am playing with a screw generator to see how fast I can make it, and customizer helps me a lot with debugging for quickly switching views and making the mesh flat to inspect if I am messing things up.
http://3d.hrg.hr/jscad/three/threejscad2.html?uri=#model.screw.js

If you consider a feature that is incomming: presets, this would allow me to have few presets where multiple values change, and I could use it to test few use cases and if models behaves correctly in few clicks instaed of changing 10 vars.

[Irev-Dev]

@jmwright, the short version is:

• For input to feed into the cad package we are using a an object of key: value pairs. Being able to use JSON would be useful but not 100% necessary, we can transform it into a different string if need be.
• For the metadata output that CadHub uses for the customizer UI, we need an array of objects. Assuming you only plan on supporting numbers, strings and booleans atm, the bare minimum needed is [{type: 'string', name: 'myString', initial: 'Hello World!'}, {type: number, name: 'myNumber', initial: 5}, {type: boolean, name: 'myBool', initial: true}]
• There are more optional params that can used (min, max, step, caption)
• To output the metadata, OpenScad just writes out a json file along with the output stl, I assume that's probably the easiest thing for cq-cli to do as well?

More details:

The discussion above is mostly what the final shape for the customizer metadata should be for Cadhub internally, however it doesn't need to match the output of each package exactly since we can't really expect that, so we have a function for each package that converts it to the Cadhub structure, though of course the closer it matches, the simpler that conversion function will be, for reference the converting function are in these files for OpenSCAD and JSCAD, but that's something I'll handle anyway for CQ. In terms of what the CadHub param data structure is this file is the source of truth, but that's a bunch of typescript types not not easy to parse instead here's an example:

This OpenSCAD code:

// slider widget for number in range
sliderWithRange = 34; // [10:100]

// step slider for number
stepSlider = 2; // [0:5:100]

// slider widget for number in range
sliderCentered = 0; // [-10:0.1:10]

// Text box for string
string="hello";

// description for boolean
boolVariable = true;

// List selection with numbers
listOfNumbers = 3; // [1,3,5,7]

// List selection with numbers with labels
listOfNumbersWithLabels = 3; // [1:One,3:Three,5:Five,7:Seven]

gets transformed to:

[
  {
    type: 'number',
    caption: 'slider widget for number in range',
    name: 'sliderWithRange',
    initial: 34,
    min: 10,
    max: 100,
    step: 1,
  },
  {
    type: 'number',
    caption: 'step slider for number',
    name: 'stepSlider',
    initial: 2,
    min: 0,
    max: 100,
    step: 5,
  },
  {
    type: 'number',
    caption: 'slider widget for number in range',
    name: 'sliderCentered',
    initial: 0,
    min: -10,
    max: 10,
    step: 0.1,
  },
  {
    type: 'string',
    caption: 'Text box for string',
    name: 'aString',
    initial: 'hello',
  },
  {
    type: 'boolean',
    caption: 'description for boolean',
    name: 'boolVariable',
    initial: true,
  },
  {
    type: 'number',
    caption: 'List selection with numbers',
    name: 'listOfNumbers',
    initial: 3,
    options: [
      {
        name: '1',
        value: 1,
      },
      {
        name: '3',
        value: 3,
      },
      {
        name: '5',
        value: 5,
      },
      {
        name: '7',
        value: 7,
      },
    ],
  },
  {
    type: 'number',
    caption: 'List selection with numbers with labels',
    name: 'listOfNumbersWithLabels',
    initial: 3,
    options: [
      {
        name: 'One',
        value: 1,
      },
      {
        name: 'Three',
        value: 3,
      },
      {
        name: 'Five',
        value: 5,
      },
      {
        name: 'Seven',
        value: 7,
      },
    ],
  },
  {
    type: 'number',
    name: 'radius',
    initial: 3,
  },
]

and like wise the params we feed back into OpenSCAD for the above is:

{
  boolVariable: true
  listOfNumbers: 3
  listOfNumbersWithLabels: 3
  aString: "hello"
  radius: 3
  sliderCentered: 0
  sliderWithRange: 34
  stepSlider: 2
}

Is that enough information, anything unclear?

[jmwright]

To output the metadata, OpenScad just writes out a json file along with the output stl, I assume that's probably the easiest thing for cq-cli to do as well?

I'll probably just have cq-cli mirror what it does with the model output (i.e. STL) where you can specify a file or just let it write to stdout. That seems to give the most flexibility in how to handle things, and should provide CadHub with what is required.

Is that enough information, anything unclear?

Thanks, I think that's all clear. I'll put updating the CadQuery integration on my short-term to-do list.