Capability schema improvements

[FloEdelmann]

Capabilities should be able to specify a whole lot more than they currently can.

1. "real" physical entity

What can be changed? (The unit is specified in brackets.)

• speed / frequency [Hz]
• duration [s]
• focus (focal length) [m]
• intensity [lm]
• rotation angle [°]
• pan angle [°]
• tilt angle [°]
• color temperature [K]
• color component (Single Color channels, e.g. red, cyan, UV) [%]
• list of colors that are on (Multi-Color channels) [?]
• sound sensitivity [?]
• no function
• gobos (gobo wheel)
• other (e.g. Auto programs)
• ... (feel free to suggest more!)

2. Stepped / continuous

Does it matter which DMX value (in the capability's DMX range) the channel is set to?

If it does, the capability could have a default value that could replace menuClick or the channel's defaultValue.

Example: Futurelight PRO Slim PAR-7 HCL, 12-channel mode

Regardless if channel 10 (Internal Programs) is set to DMX value 61, 99 or 120, the capability Internal Program 2 (DMX range [61, 120]) is activated.

In contrast, the resulting color does change if channel 9 (Color Presets) is set to DMX value 11 (red) or 30 (yellow), although both correspond to the same capability (Red 100% / Green increasing / Blue 0%) with DMX range [11, 30].

3. DMX correspondence

What value of the physical entity (in the respective unit) does the DMX range correspond to? If a specific value is unknown, percentage values can be applied for all entities.

This makes the channel's invert property useless, since on could just map physical values 100%-0% to DMX values 0-255.

4. Other

• name and menuClick can sometimes be inferred from the physical entity and its range (as a default)
• focal length infinity should be allowed
• rotation, pan and tilt direction should be specified (clockwise / counterclockwise) → from which point of view?
• Is the channel allowed to be faded smoothly from one value to another? (currently specified by channel's crossfade property)
  • should be allowed e.g. for color or intensity capabilities
  • should be disallowed e.g. for Internal Programs or strobe capabilities
• Radical suggestion: If the capabilities have "types", we possibly don't even have to specify channel types anymore!
• Think about Allow infinite Pan / Tilt #352 and Gobo manager, Gobo / Color / Effect Wheel schema #177 too!

[FloEdelmann]

A new release of QLC+ is coming up, and it seems that it will use a new fixture definition file format:

Also, the 3D preview drags in another interesting topic: fixture definitions must improve ! For example, QLC+ doesn't know if a pan is clockwise or counterclockwise. Therefore the whole preview could be messed up.
I am already thinking about a rework that will introduce more accurate information for the 3D simulation, but that's another huge work to do.
QLC+ forum post: QLC+ 5 Preview - Update #3

One above all, I will need a lot of manpower for a big rework I intend to do on fixture definitions. Again, I need to write down the enums to start with. I'll create a new branch in the next weeks.
QLC+ forum post: How to help?

We should team up with Massimo Callegari to help making the new format as well-designed as possible.

Edit by @fxedel: Massimo published a document describing the new features of the .qxf format. The section "Capability accuracy" is the equivalent to this issue.

[fxedel]

One possibility might be introducing capability types:

• Instead of giving the whole channel a type, we exactly specify what a capability does by giving it a precise type
• All properties of a capability:
  • dmxRange: renamed from range to better distinguish from physical entity ranges
  • type: required; see list below for possible values
  • comment: free text, optional; is always allowed to further describe the capability, especially if the type doesn't fit perfectly
  • type-specific properties (there can exist 0-n possible properties per type)
    • Physical entities like speed, angle (see below): Always entered as string (with a unit, if needed), like "10Hz", "5°", "0%", "9" -> the capability type defines the entity, the entity defines the list of possible units; there exist entity-specific keywords that replace a percentage value
    • Special properties that are no physical entities, like strobeType or colors
    • Each of these can also be an array of two values, describing different states for start and end of the capability (like "speed slow-fast")
  • menuClick: Legacy, maybe replace this with auto-generated field?
  • switchChannels: for switching channels as usual

This is similar to @mcallegari's idea of capability presets in QLC+ (see mcallegari/qlcplus#1026)

Possible entities and keywords

Entity	Allowed Units	-100%	-1%	0%	1%	100%
Speed	Hz, %	–	–	–	slow	fast
DirectionalSpeed	Hz, %	fast CCW	slow CW	stop	slow CW	fast CWW
Time	s, ms, %	–	–	instant	short	long
Distance	m, %	–	–	–	near	far
Brightness	lm, %	–	–	off	dark	bright
ColorTemperature	K, %	–	–	–	warm	cold
FogOutput	m³/min, %	–	–	off	weak	strong
RotationAngle	°, %	–	–	–	–	–
BeamAngle	°, %	–	–	closed	narrow	wide
Factor	(no unit), %	–	–	off	low	high
Index	(no unit)	–	–	–	–	–
Percent	%	–	–	–	–	–
IrisPercent	%	–	–	closed	–	open

Possible capability types

required properties are italic

• Nothing
• ShutterOpen
• ShutterClosed
• StrobeEffect
  • strobeType: one of Normal (default), Random, Pulse, PulseRandom, RampUp, RampUpRandom, RampDown, RampDownRandom
• StrobeSpeed
  • speed (Speed)
  • strobeType: one of Normal (default), Random, Pulse, PulseRandom, RampUp, RampUpRandom, RampDown, RampDownRandom
• StrobeDuration
  • time (Time)
  • strobeType: one of Normal (default), Random, Pulse, PulseRandom, RampUp, RampUpRandom, RampDown, RampDownRandom
• Intensity
  • brightness (Brightness)
• ColorIntensity
  • color: one of our predefined Single Colors (Red, Green, Blue, White, Amber, etc.)
  • brightness (Brightness)
• Color
  • colors: array of visible colors as hex codes (e.g. ['#ffff00'] if red and green LEDs are on that mix to yellow; ['#ff0000', '#00ff00'] if red and green laser beams are on that don't mix)
  • use colorsStart and colorsEnd instead of colors to declare a color change from the start to the end of the range
• ColorJump
  • speed (DirectionalSpeed)
• ColorFade
  • speed (DirectionalSpeed)
• ColorTemperature
  • colorTemperature (ColorTemperature)
• Pan
  • angle (RotationAngle)
• PanContinuous
  • speed (DirectionalSpeed)
• Tilt
  • angle (RotationAngle)
• TiltContinuous
  • speed (DirectionalSpeed)
• PanTiltSpeed
  • speed (Speed)
• Effect
  • effectIntensity (Factor)
  • speed (DirectionalSpeed)
• EffectIntensity (global, don't set an effect)
  • effectIntensity (Factor)
• EffectSpeed (global, don't set an effect)
  • speed (DirectionalSpeed)
• GoboIndex
  • index (Index): 0 for open, 1 for Gobo 1, 1.5 for Gobo 1/2 split, etc.
• GoboShake
  • index (Index)
  • speed (Speed)
• GoboStencilRotationAngle
  • angle (RotationAngle)
• GoboStencilRotationSpeed
  • speed (DirectionalSpeed)
• GoboWheelRotationAngle
  • angle (RotationAngle)
• GoboWheelRotationSpeed
  • speed (DirectionalSpeed)
• ColorWheelIndex
  • index (Index): 0 for open, 1 for Color 1, 1.5 for Color 1/2 split, etc.
• ColorWheelRotationAngle
  • angle (RotationAngle)
• ColorWheelRotationSpeed
  • speed (DirectionalSpeed)
• Focus
  • distance (Distance)
• Zoom
  • angle (BeamAngle)
• Iris
  • openPercent (IrisPercent)
• IrisEffect
  • speed (Speed)
• Frost
  • frostIntensity (Percent)
• FrostEffect
  • speed (Speed)
• PrismOff
• PrismOn
  • angle (RotationAngle)
  • speed (DirectionalSpeed)
• PrismRotationAngle
  • angle (RotationAngle)
• PrismRotationSpeed
  • speed (DirectionalSpeed)
• FogOff
• FogOn
  • fogOutput (FogOutput)
  • fogType: either Fog or Haze
• FogOutput
  • fogOutput (FogOutput)
• FogType
  • fogType: either Fog or Haze
• RotationAngle
  • angle (RotationAngle)
• RotationSpeed
  • speed (Speed)
• Maintenance
  • parameter (Factor)
  • hold (Time)
• Generic

[fxedel]

@FloEdelmann I'm wondering how to shorten the syntax for channels that currently have no capability at all. Would it make sense to allow instead of this:

    "Master Dimmer": {
      "capabilities": [
        {
          "dmxRange": [0, 255],
          "type": "Intensity",
          "brightnessStart": "off",
          "brightnessEnd": "bright"
        }
      ]
    },

also this:

    "Master Dimmer": {
      "type": "Intensity",
      "brightnessStart": "off",
      "brightnessEnd": "bright"
    },

as a shorthand for single-capability channels? Unfortunately, this will make the schema and the model much more complicated. But it's readable and needs just 3 instead of 8 lines of codes (only for the capability).

Edit: Better allow this syntax, which is a good tradeoff between shortness, readability and JSON Schema simplicity:

    "Master Dimmer": {
      "capability": {
        "type": "Intensity",
        "brightnessStart": "off",
        "brightnessEnd": "bright"
      }
    },