Skip to content

Custom JSON Fixtures

Jump to bottom Edit New page
Mark Slee edited this page Jul 3, 2023 · 18 revisions

Overview

Custom lighting fixtures that cannot be simply represented as a strip, arc, or grid can be defined in custom fixture files. These JSON-formatted files should be placed in the Fixtures folder with the .lxf file suffix.

Here is example syntax indicating all possible fields. Fields are described in greater detail below.

{
  "label": "Custom",

  "tags": [ "custom", "another" ],

  "parameters": {
    "intParam": {
      "type": "int", "default": 0, "min": 0, "max": 100,
      "label": "Int Param",
      "description": "Example integer parameter"
    },
    "floatParam": {
      "type": "float", "default": 0.5,
      "label": "Float Param",
      "description": "Example float parameter"
    },
    "stringParam": {
      "type": "string", "default": "text",
      "label": "String Param",
      "description": "Example string parameter, holding a hostname"
    },
    "boolParam": {
      "type": "boolean", "default": false,
      "label": "Bool Param",
      "description": "Example boolean parameter"
    }
  },

  "components": [
    { "type": "points", "coords": [ { "x": 0, "y": 0, "z": 0 } ] },

    { "type": "strip",
      "x": 0, "y": 0, "z": 0,
      "numPoints": 40, "spacing": 10, "yaw": 45, "pitch": 45, "roll": 45 },

    { "type": "strip",
      "x": 0, "y": 0, "z": 0,
      "numPoints": 50, "spacing": 20,
      "direction": { "x": 1, "y": -1, "z": 0.5 } },

    { "type": "arc", 
      "x": 0, "y": 0, "z": 0,
      "numPoints": 50, "mode": "center", "radius": 100, "degrees": 90,
      "yaw": 0, "pitch": 0, "roll": 0 },

    { "type": "arc",
      "x": 0, "y": 0, "z": 0,
      "numPoints": 50, "mode": "origin", "radius": 100, "degrees": 90,
      "direction": { "x": 3, "y": 1, "z": -1 } },

    { "type": "arc",
      "x": 0, "y": 0, "z": 0,
      "numPoints": 50, "mode": "origin", "radius": 100, "degrees": 90,
      "normal": { "x": 3, "y": 1, "z": -1 }
    },

    { "type": "ChildJSON", "x": 10, "yaw": "90", "childStringParameter": "${stringParam}" }
  ],

  "outputs": [
    {
      "protocol": "artnet",
      "universe": 0,
      "host": "127.0.0.1",
      "start": 0, "num": 50
    },
    {
      "protocol": "sacn",
      "host": "${stringParam}",
      "start": 50, "num": 30, "reverse": true,
      "byteOrder": "rgbw"
    }
  ],

  "meta": {
    "key1": "val2",
    "key3": "val4"
  }
}

Top-Level

  • label - this optional string field supplies a default label that will be displayed for any new instantiation of this fixture type

  • tags - an optional array of string identifiers that can be used to query this type of fixture in the LXModel hierarchy, tags may only contain the characters [A-Za-z0-9_.-]

  • tag - an optional single string identifier, same as tags but one string value instead of an array

Parameters

Under the optional parameters field, variables can be defined. The parameters field must hold a dictionary. The keys are the names of parameters which can be later substituted. The UI will automatically display controls for modifying the values of these parameters, and their values can be used in variable substitutions for other values in the JSON file, or a child JSON file.

Fields

  • type: required, one of int,float,boolean,string
  • default: required, a default value for the parameter, must be of correct type
  • label: optional, a human-readable label for the parameter in the UI (if not supplied, the JSON key is used)
  • description: optional, a description of the functionality of this parameter that the UI will show on hover
  • min: optional, for integer/float parameters only, a minimum value
  • max: optional, for integer/float parameters only, a maximum value

Substitutions

The keys in this JSON dictionary can be referenced via the syntax "${varKey}", where varKey is the key for this parameter in the JSON dictionary. The substitution must appear inside a quote-encapsulated string. Keys must only be alphanumeric.

Basic mathematical operators +,-,*,/ are available to form simple expressions for integer and floating point values.

In the case of boolean expressions, the operators &,|,! are available for logical AND, OR, NOT.

Components

Components of the custom fixture are enumerated in a JSON array under the components key. Each component element is a JSON dictionary which indicates its type in the type field.

Points

A component of type points field holds an array of individual points. Coordinates are stored in the coords fields, an array of dictionaries specifying:

  • x: float X-coordinate of the point
  • y: float Y-coordinate of the point
  • z: float Z-coordinate of the point

Strip

A component of type strip has the following fields:

  • x: float X-coordinate of the start of the strip
  • y: float Y-coordinate of the start of the strip
  • z: float Z-coordinate of the start of the strip
  • numPoints: integer number of points in the strip
  • spacing: float spacing between points in the strip
  • tag/tags: optional string identifier tags for this strip
  • meta: an optional JSON dictionary of string key-value pairs passed to the model
  • output/outputs: optional outputs may be specified here

The orientation of the strip may be specified in one of two ways.

  • direction: a JSON dictionary with fields x,y,z that specify the direction (not the spacing) of the strip

Alternatively, the strip may be rotated in space geometrically:

  • yaw: Rotation about the vertical axis in degrees
  • pitch: Rotation about the horizontal axis in degrees
  • roll: Rotation about the depth axis in degrees

Arc

A component of type arc has the following fields:

  • x: float X-coordinate of the start of the strip
  • y: float Y-coordinate of the start of the strip
  • z: float Z-coordinate of the start of the strip
  • mode: one of center or origin which specifies whether the given position is the center of the arc, or its first point
  • numPoints: integer number of points in the arc
  • degrees: float number of degrees the arc rotates around
  • tag/tags: optional string identifier keys for this arc
  • meta: an optional JSON dictionary of string key-value pairs passed to the model
  • output/outputs: optional outputs may be specified here

The orientation of the arc may be specified in one of three ways.

  • normal: a JSON dictionary with fields x,y,z that specifies the direction of a normal vector around which the arc rotates
  • direction: a JSON dictionary with fields x,y,z that specifies the direction of a tangent line at the arc's origin

Alternatively, the arc may be rotated in space geometrically, similar to a strip:

  • yaw: Rotation about the vertical axis in degrees
  • pitch: Rotation about the horizontal axis in degrees
  • roll: Rotation about the depth axis in degrees

LXF children

A JSON fixture may contain and reference other child JSON fixtures. Each of these child objects is a JSON dictionary with the following fields.

  • type: string which refers to the name of the child .lxf file
    • e.g. "child" would be used to reference Fixtures/child.lxf
    • e.g. "subdir/child" would be used to reference Fixtures/subdir/child.lxf
  • x: float X-coordinate of the child, relative to parent
  • y: float Y-coordinate of the child, relative to parent
  • z: float Z-coordinate of the child, relative to parent
  • yaw: Rotation about the vertical axis in degrees, relative to parent
  • pitch: Rotation about the horizontal axis in degrees, relative to parent
  • roll: Rotation about the depth axis in degrees, relative to parent
  • scale: Optional float to scale the whole child fixture by some factor
  • tag/tags: optional string identifier keys for this arc
  • meta: an optional JSON dictionary of string key-value pairs passed to the model
  • output/outputs: optional outputs may be specified here

If the child fixture defines any custom parameters, those values may be specified directly on the child JSON dictionary.

Outputs

The JSON fixture may define a number of output packets/protocols under the outputs JSON array. If only a single packet is needed, then this may be supplied on the output field. Output JSON elements may also be attached directly to a single component child of the fixture.

  • protocol: Required string, one of the following:
    • artnet/artdmx: an Art-Net DMX packet
    • artsync: an ArtSync packet, with no payload (sent after all normal packets)
    • sacn/e131: Streaming ACN E1.31
    • ddp: Distributed Display Protocol http://www.3waylabs.com/ddp/
    • opc: Open Pixel Control http://openpixelcontrol.org/
    • kinet: Color Kinetics KiNET
  • transport: Optional string, only supported for OPC, one of udp/tcp
  • host: String hostname for the destination
  • port: Optional port number if overriding the protocol default
  • byteOrder: Byte order of pixel data, a three or four character string containing rgb and optionally w
  • enabled: Optional boolean enabled flag, defaults to true when not present
  • fps: Optional value to set a FPS limit for any packets derived from this output (0-300), if not specified the default engine rate is used

Protocol Specific Fields

  • universe: DMX universe, only when using the artnet or sacn protocol
  • dataOffset: Data offset, only when using the ddp protocol
  • channel: OPC channel when using the opc protocol, otherwise DMX channel for artnet/sacn/kinet
  • offset: OPC offset, when using opc protocol
  • kinetPort: KiNET port number, only when using the kinet protocol

Indexing

A number of indexing fields specify which LEDs in the fixture should be encoded into this packet. The fields are as follows:

  • start: The integer index, relative to this fixture, of the first point to include in this packet (default is 0)
  • num: The integer total number of pixels to send in this packet (if not specified, all points in this fixture are included)
  • stride: Optional, integer number of points to jump by for each sequential pixel (default is 1)
  • repeat: Optional, repeat each output point N times (default is 1)
  • reverse: Optional boolean, if true then the range defined will be sent in reverse order

To construct a packet in which the encoded points are not all sequential, an array of segments may be defined. This JSON array is a list of JSON dictionaries, each defining a segment using the fields above. All of the segments will be concatenated to construct the packet.

Note that output/outputs may be specified at the top level, or directly on strip, arc, or child definitions. In that case, the supplied indices are relative only to the points defined by the sub-fixture, not the entire parent fixture.

Metadata

Optional string key-value pair metadata may be passed to the model. This can be queried by animation code using the meta(String key) method of the LXModel class.

Metadata may be supplied at the top-level, or attached directly to any sub-fixture definition (whether a strip, arc, or child), using the meta key.

© 2020 LX Studio — Heron Arts LLC

Add a custom sidebar
Clone this wiki locally