Skip to content

Custom JSON Fixtures

Jump to bottom Edit New page
Mark Slee edited this page Nov 25, 2020 · 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",

  "modelKeys": [ "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"
    }
  },

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

  "strips": [
    {
      "x": 0, "y": 0, "z": 0, "numPoints": 40, "spacing": 10,
      "yaw": 45, "pitch": 45, "roll": 45
    },
    {
      "x": 0, "y": 0, "z": 0, "numPoints": 50, "spacing": 20,
      "direction": { "x": 1, "y": -1, "z": 0.5 }
    }
  ],

  "arcs": [
    {
      "x": 0, "y": 0, "z": 0,
      "mode": "center", "radius": 100, "degrees": 90,
      "yaw": 0, "pitch": 0, "roll": 0
    },
    {
      "x": 0, "y": 0, "z": 0,
      "mode": "origin", "radius": 100, "degrees": 90,
      "direction": { "x": 3, "y": 1, "z": -1 }
    },
    {
      "x": 0, "y": 0, "z": 0,
      "mode": "origin", "radius": 100, "degrees": 90,
      "normal": { "x": 3, "y": 1, "z": -1 }
    }
  ],

  "children": [
    { "type": "child.lxf", "x": 10, "yaw": "90", "childStringParameter": "${stringParam}" }
  ],

  "outputs": [
    { "protocol": "artnet", "host": "${stringParam}", "start": 0, "num": 100 },
    { "protocol": "artnet", "host": "${stringParam}", "start": 100, "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

  • modelKeys - an optional array of string identifiers that can be used to query this type of fixture in the LXModel hierarchy.

  • modelKey - an optional single string identifier, same as modelKeys 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 parameters only, a minimum value
  • max: optional, for integer 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.

Geometry

Points

The points field holds an array of individual points that are part of this fixture, if it has any. Each point has the following fields:

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

Strips

The strips field holds an array of strips that are part of this fixture. Each 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
  • modelKey/modelKeys: optional string identifier keys 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

Arcs

The arcs field holds an array of arcs that are part of this fixture. Each 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
  • modelKey/modelKeys: 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

Children

Under the children field, a JSON fixture may contain and reference an array of 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
  • modelKey/modelKeys: 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.

  • protocol: Required string, one of the following:
  • 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

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, only when using the opc procotol
  • 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)
  • 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).

© 2020 LX Studio — Heron Arts LLC

Add a custom sidebar
Clone this wiki locally