Color Definitions and Settings: XML vs JSON vs ???

[Kohila]

As consumed by Stud.io, custom colors must be contained within two different files: CustomColorSettings.xml and CustomColorDefinitions.txt.

As a feature of this project, these files are auto-generated during colorpack build time from the unique custom colors within the colors/ directory. As it's not optimal/maintainable to have two unique .txt and .xml files for every color, both elements of a custom color's data will reside within a single file that is placed in a proper location within the colors/ directory.

This solution provides significant benefits to the project's structure and ease of use. However, combining a color's definition and settings data presents some interesting problems.

A color's data within CustomColorDefinitions.txt will need to be translated into a better language, full stop. The tab whitespace delimited row of data isn't extensible/readable. A color's data within CustomColorSettings.xml, however, can either stay in XML format or be translated into a different language. Again, this data will be formatted and saved appropriately during build time.

To summarize the problem: The single file that contains a color's data can take many different forms, and we need to decide on one.

I wanted to drop three possible options here as examples to get the discussion rolling. I'm not endorsing any specific option; I'm merely presenting them as three logical ways to go about this.

Option 1: .JS File - JSON Definition, XML Settings

/**
 * Color settings in XML format
 */

const XML = `
<material displacement_method="bump" heterogeneous_volume="False" name="SOLID-SAMPLE_COLOR" use_local_tuning="False" use_mis="True" use_transparent_shadow="True" volume_interpolation_method="linear" volume_sampling_method="multiple_importance">
    <shader>
        <color name="Sample_Color" value="1.0 1.0 1.0" />
        <!-- The rest of the color settings go here . . . -->
    </shader>
</material>
`

/**
 * Color Definition in JSON format
 */

export default color = {
  id: {
    studio: "12345678",
    bricklink: "12345678",
    ldraw: "12345678",
    ldd: "12345678",
  },
  name: {
    studio: "Sample Color",
    bricklink: "Sample Color",
    ldraw: "Sample Color",
    ldd: "Sample Color",
  },
  category: {
    name: "Solid Colors",
    nickname: "Gloss Colors",
  },
  groupId: "-1",
  rgb: "#FFFFFF",
  alpha: "1",
  instructions: {
    rgb: "#FFFFFF",
    cmyk: "0,0,0,0",
  },
  notes: "(Future location of BCC defined metadata, e.g. Color Author)",
  xml: XML,
}

Option 2: .JS File - JSON Definition, JSON Settings

/**
 * Color settings in JSON format
 */

const JSON = {
  material: {
    _displacement_method: "bump",
    _heterogeneous_volume: "False",
    _name: "SOLID-SAMPLE_COLOR",
    _use_local_tuning: "False",
    _use_mis: "True",
    _use_transparent_shadow: "True",
    _volume_interpolation_method: "linear",
    _volume_sampling_method: "multiple_importance",
    shader: {
      color: {
        _name: "Sample_Color",
        _value: "1.0 1.0 1.0",
      },
    },
  },
}

/**
 * Color Definition in JSON format
 */

export default color = {
  id: {
    studio: "12345678",
    bricklink: "12345678",
    ldraw: "12345678",
    ldd: "12345678",
  },
  name: {
    studio: "Sample Color",
    bricklink: "Sample Color",
    ldraw: "Sample Color",
    ldd: "Sample Color",
  },
  category: {
    name: "Solid Colors",
    nickname: "Gloss Colors",
  },
  groupId: "-1",
  rgb: "#FFFFFF",
  alpha: "1",
  instructions: {
    rgb: "#FFFFFF",
    cmyk: "0,0,0,0",
  },
  notes: "(Future location of BCC defined metadata, e.g. Color Author)",
  json: JSON,
}

Option 3: .XML File - XML Definition, XML Settings

<!--
  Color definition in XML format
-->
<definition>
  <id studio="12345678" bricklink="12345678" ldraw="12345678" ldd="12345678" />
  <name studio="Sample Color" bricklink="Sample Color" ldraw="Sample Color" ldd="Sample Color" />
  <values rgb="#FFFFFF" alpha="1.0" groupId="-1" />
  <instructions rgb="#FFFFFF" cmyk="0,0,0,0" />
  <notes>
    <!-- (Future location of BCC defined metadata, e.g. Color Author) -->
  </notes>
</definition>

<!-- 
  Color settings in XML format
-->
<settings>
  <material displacement_method="bump" heterogeneous_volume="False" name="SOLID-SAMPLE_COLOR" use_local_tuning="False" use_mis="True" use_transparent_shadow="True" volume_interpolation_method="linear" volume_sampling_method="multiple_importance">
    <shader>
      <color name="Sample_Color" value="1.0 1.0 1.0" />
      <!-- The rest of the color settings go here . . . -->
    </shader>
  </material>
</settings>

[violetgynoid]

I'm throwing my hat in the ring for options 1 or 2 - reserving an .xml filename for the actual color settings will make it easier to write tutorials for the general public who don't know computer basics.

[Kohila]

@violetgynoid Based on your feedback, I just wanted to restate one of the main points from my original post: there will NOT be a .XML file reserved only for a color's Settings. The idea is that ALL of the unique data for a color -- ie. a color's Definition and Settings -- will reside in a SINGLE file. The goal of this issue is to decide 1. what language(s) the Definition and Settings data is encoded in prior to colorpack build time, and 2. what file type that data is saved as in the colors/ directory.

[Kohila]

In an effort to provide comprehensive examples of the best candidates for color data encoding, I wanted to throw YAML as an option as well. While YAML is a superset of JSON, I do think that an argument could be made that YAML is easier to read, write, and learn.

Option 4: .YAML File - YAML Definition, YAML Settings

---
# Color Definition in YAML format
definition:
  id:
    studio: 12345678
    bricklink: 12345678
    ldraw: 12345678
    ldd: 12345678
  name:
    studio: Sample Color
    bricklink: Sample Color
    ldraw: Sample Color
    ldd: Sample Color
  category:
    name: Solid Colors
    nickname: Gloss Colors
  groupId: -1
  rgb: #FFFFFF
  alpha: 1
  notes: (Future location of BCC defined metadata, e.g. Color Author)

# Color Settings in YAML format
settings:
  material:
      _displacement_method: bump
      _heterogeneous_volume: False
      _name: SOLID-SAMPLE_COLOR
      _use_local_tuning: False
      _use_mis: True
      _use_transparent_shadow: True
      _volume_interpolation_method: linear
      _volume_sampling_method: multiple_importance
      shader:
        color:
          _name: Sample_Color
          _value: 1.0 1.0 1.0
          # The rest of the color settings go here . . .