template_spec_with_comments.json

// Specification of a 2D pattern template that describes the structure and the ways it can be modified
// All of the string constants here are keywords with exeption of panel and parameter ids
{
  
  // Properties give additional instructions on how to read this template file
  "properties": {
    // Describes the way cordinates of the curvature control points are specified in this template. 
    // Allowed values:
    // * "relative" -- Coordinates are given in local edge frame theating an edge as vector (1, 0)
    // * "absolute" -- Coordinated are given in world frame, the same coordinate space as panel vertices.  
    // The chosen convention has to be used for all edge curvature specifications in the pattern!
    "curvature_coords": "relative", 
    
    // indicates if each panel translation should be normalized to put local origin in the middle
    // of the panel.
    // The world translation vector is adjusted s.t. world position of vertices do not change when rotation is zero
    // BUT if rotation is present, normalization might affect it
    // It's only recommended to use this option for the benefits of easy editing
    "normalize_panel_translation": false, 
    
    // indicates how many units used for pattern specification fits in 1 meter
    // the value is used to standardize units to cm on loading 
    "units_in_meter": 300,

    // Indicates that the pattern follows the convention of edge loops traversal in every panel 
    // (needed for datasets uniformity)
    // If not given (or 'false'), the pattern will be updated to adhere to convention on load
    //
    // Convention: 
    //  * the edges are ordered to traverse the panel in counter-clockwise direction
    //  * the start vertex of the edge loop either 
    //      * has the same id as in (normalized) template it was drawn from (if this pattern is a sample)
    //      * or is the most low-left vertex of a panel
    "normalized_edge_loops": true
  },
  // Section that fully describes the pattern. This section is enough to render a pattern in whatever form needed.  
  "pattern": {
    // List of panels that constitute the pattern. The list is unordered
    "panels": {
      // Description of a panel named "front". Panel name can be chosen arbitrarily and serves as its id in other sections of the spec. 
      // it's better be meaningful for visualization and debug puproses
      "front": {
        // Full list of vertices (corners) of a panel.
        "vertices": [
          // 2D vertex coordinates (as panel is 2D structure). They are
          // * given in xOy with Y facing up. 
          // * Use the same units as used by the body it'll be simulated on -- realistic measurements and meters as units
          // * Coordinates are allowed to encode xOy panel translation: 
              // On load, positions are normalized to have origin (0, 0) at the panel center, 
              // the discovered vertices offset is added to 3D translation vertor (below)
          // Vertex id is its position in this list, starting from 0
          // Order, in which vertices are specified, does NOT matter
          [-54.470, -15.004], 
          [55.530, -15.004], 
          [132.530, -195.004],
          [-131.470, -195.004]
        ],
        // Sequence of edges that describes panel border.
        // Listing edges sepaeately allows giving them properties (stright or curved) and directions: 
        // * Edges are directed, 
        // * the list IS ordered. 
        // * Connected together as specified, edges form a directed closed loop that represents panel border.
		    // * The traversal order of vertices with edges defines the front (normal direction) of a panel
        // Edge id is its position in this list, starting from 0
        "edges": [
          // each edge is represented as a simple structure
          {
            // ids of vertices this edge connects represented as a list of 2 ids
            // edge has a direction: it goes from the first endpoint (start) to the second (end)
            "endpoints" : [1, 0],
            // edge can be a Quadratic Bezier curve. 'curvature' gives coordinated of the curve control vertex
            // Coordinates are given in local frame following "relative" convention stated in "properties" section
			      // but could also be given as absolute coordinates
            "curvature": [
              0.5,
              0.2
            ]
          },
          {
            "endpoints" : [0, 3]
            // an edge can simply be a straight line, in this case, there is no need to specify curvature
          },
          {
            "endpoints" : [3, 2],
            "curvature": [
              0.5,
              -0.2
            ]
          },
          {
            "endpoints": [
              2,
              1
            ]
          }
        ],
        // 3D translation vector for 3D placement of the panel
        "translation" : [0, 0, 56.280],
        // 3D rotation vector for 3D placement of the panel
        // Given in XYZ Euler angles (as in Maya!)
        "rotation" : [0, 0, 0]
      },
      // Second panel of this template "skirt". Same principles
      "back": {
        "vertices": [
          [-54.470, -15.004], 
          [55.530, -15.004], 
          [132.530, -195.004],
          [-131.470, -195.004]
        ],
        // all edges are straight
        "edges": [
          {
            "endpoints" : [0, 1]
          },
          {
            "endpoints" : [1, 2]
          },
          {
            "endpoints" : [2, 3]
          },
          {
            "endpoints" : [3, 0]
          }
        ],
        "translation" : [0, 0, -46.530],
        "rotation" : [0, 0, 0]
      }
    },
    // Sewing information of which edges should be stitched together to form a garment
    // the ordering of stitches does not matters
    "stitches": [
      // each stitch is just a list of 2 edges to connect. 
      // (we only support 1-to-1 stitches)
      [
        // edge locator ensures uniquness of the reference
        {
          // for edge identification, we need to know the panel name 
          "panel": "front",
          // and the edge id in that panel.
          "edge": 1
        },
        // there could be one or multiple 'to's -- e.g. to describe sleeves
        {
          "panel": "back",
          "edge": 1
        }
      ],
      [
        {
          "panel": "front",
          "edge": 3
        },
        {
          "panel": "back",
          "edge": 3
        }
      ]
    ],
    // Optional section -- it may be omited in template definitions.
    "panel_order": [
      // Defines a specific ordering of panels within pattern by listing panel names in the needed order
      // Typically appears in template samples to esure panel order consistency across dataset in the downstream applications.
      // BUT this is an artificial construct (as there is no natural order of panels thus is not part of required pattern definition)
      // If not provided but needed, the downstream application may generate panel order automatically (e.g. based on 3D translation of panels).
      "back",
      "front"
    ]
  },
  // This section describes how the pattern above can be changed
  // as a list of multiplicative parameters that influence panel edges
  // order of parameter definitions here doesn't matter, and the application order is described separately (below)
  "parameters": {
    // a parameter named "length". Parameter name can be chosen arbitry and serves as its id in other sections of the spec. 
    // it's better be meaningful for debug puproses
    "length": {
      // The value of the parameter that corresponds to pattern state described above: 
      // when the value is updated, pattern information (vertex positions) should be updated as well
      // In templates, value equals 1 for every parameter -- indicating that no changes has been made
      // there could be one or more values for a parameter depending on the parameter type 
      // (see example below for curve parameters)
      // For 'length' parameters value is a scalar
	  // Note! Try to avoid zero values, as the result becomes irreversible (impossible to restore original value)
      "value": 1,
      // The allowed range a parameter could take. Allows to control intensity of change 
      // when parameter is varied
      "range": [
        0.3,
        2
      ],
      // parameter type: it dictates how the parameter variation should be processed
      // Some parameter object properties (number of values, structure of edge_lists) vary between types.
      // Allowed types:
      // * "length" -- influece the length of edges it applies to
      // * "curve" -- see below -- controls edge curvature
      "type": "length",
      // List of panels and edges the parameter applies to
      // the order does NOT matter
      // Note that such properties as Symmetric application of a parameter or - Applying parameter to both sides of the stitch
      // are not guaranteed by the system and shoud be ensured through accurate parameter influence description
      "influence": [
        // each influence instance corresponds to a panel and 1 or more edges within it
        // there is NO need to list panels that don't have edges influenced by the parameter
        {
          // panel name
          "panel": "front",
          // list of edges within panel. 
          // Order DOES matter. It might influence the result of applying the parameter
          "edge_list": [
            // For the 'length' parameter type, each entry is an object. For "curve", see example below
            {
              // edge id is within the panel
              "id": 1,
              // A vector along which to perform extention\srink of the edge
              // if not given, extention happens along the edge itself
              // positive\neg direction don't matter ([0, 1] and [0, -1] will give the same outcome)
              "along": [0, 1],
              // the vertex of the edge that should be moved when parameter is applied.
              // It can be used to ensure simmetry of parameter application to different edges 
              // and to preserve adjusent edges
              // Allowed values: 
              // * 'start' -- only the first vertex of the edge moves
              // * 'end' -- only the last vertex of the edge moves
              // * 'both' -- both verticed of the edge move equally
              "direction": "end"
            },
            // one more edge within same panel influenced by the parameter
            {
              // this is a 'meta-edge': a section of the panel border as a list of consecutive edges 
              // meta-edge will be treated as an edge from start of the first edge to end of the last edge
              // all the inner edges will be naturally stretched along the meta-edge direction
              "id": [2, 3],
              // In this case, towards the start vertex of meta-edge
              "direction": "start"
            }
          ]
        },
        // one more panel with edges influenced by the parameter
        {
          "panel": "back",
          "edge_list": [
            {
              "id": 1,
              "direction": "end"
            },
            {
              "id": 3,
              "direction": "start"
            }
          ]
        }
      ]
    },
    // parameter of 'additive_length' type
    // These parameters extend\shink edges with param value directly, without regard to current edge length 
    "low_wide": {
      // So, the neutral (template) value is now Zero instead of One
      "value": 0,
      // Note: range here is unit-dependent! If pattern is scaled, the range here should also be updated
      "range": [
        -100,
        100
      ],
      // type tag: 
      "type": "additive_length",
      // influence definition is the same as for other parameters
      // 'along' type of extention is also supported
      "influence": [
        {
          "panel": "front",
          "edge_list": [
            {
              "id": 2,
              "direction": "both"
            }
          ]
        },
        {
          "panel": "back",
          "edge_list": [
            {
              "id": 2,
              "direction": "both"
            }
          ]
        }
      ]
    },
    // a parameter of 'curve' type
    // ! Note the differences in the object structure
    "low_wide_curve": {
      // the 'curve' parameters are allowed to have two values
      // that contol x & y components of a control vertex of edges they apply to
      // IF there is only one (scalar) value, it applies to the Y component of control vertex
      "value": [
        1,
        1
      ],
      // since there are two values, there are also two ranges
      // => they can be the same or different!
      "range": [
        [
          0,
          1
        ],
        [
          -1,
          1
        ]
      ],
      "type": "curve",
      "influence": [
        {
          "panel": "front",
          // !! Note that edge list is simplified to be
          // just a simple list of edge ids within the panel
          // Order DOES matter, as before
          "edge_list": [
            2
          ]
        }
      ]
    }
  },
  // Parameters might be interdependent: One edge extension could lead to change of direction in another edge.
  // But it's guaranteed that parameters are processed one by one:
  // moving to next parameter only when all the edges dependent on current parameter have been updated. 
  //
  // This section described the order in which parameneters are applied when modifuing the template	
  // An ORDERED list of parameter names
  //
  // It's recomenneded to only change the order for templates (patterns with parameters in default state). Otherwise,
  // template restoration might become impossible
  "parameter_order": [
    "length",
    "low_wide",
    "low_wide_curve"
  ], 

  // This section allows to define constraints on parametrized panel
  // No matter how parameter values are changes, these contraints are ensured to hold
  // They are applied after all the parameter values are applied
  "constraints": {
    // Constraints are named and unordered
    // The order of application is defined in section 'constraint_order' (below)
    // At the moment, only constraints of type 'length_equality' are supported
    "side_stitches": {
      // this type ensures that all the [meta] edges listed in "influence" sections 
      //  have the same length. 
      // More spesifically:
      //    * all the listed edges are changed s.t. their length matches 
      //      the MEAN length of all the edges in the list
      "type": "length_equality",

      // influence specification follows that of a parameter with type "length" (multiplicative)
      // but the values are specified per edge
      "influence": [
        {
          "edge_list": [
            {
              // As with parameters, edge secification supports
              //  * direction to apply change to 
              "direction": "end", 
              //  * changes along the given vector
              // if this info is specified, than all of the contraint calculations and
              // conditions are applied along this vector 
              "along": [0, 1],
              //  * individual edges
              //  * meta-edges -- a sequential collection of edges representing section of the panel border
              "id": 1, 
              // Info SPECIFIC to constraint definition
              // value is defined per edge description and
              // allows to invert the influence of constraint
              // Value specifies the scaling factor that was applied to this (meta) edge
              // to ensure constraint is held
              "value": 1
            },
            {
              "direction": "start", 
              "id": 3, 
              "value": 1
            }
          ], 
          "panel": "front"
        }, 
        {
          "edge_list": [
            {
              "direction": "end", 
              "id": 3, 
              "value": 1
            },
            {
              "direction": "start", 
              "id": 1, 
              "value": 1
            }
          ], 
          "panel": "back"
        }
        
      ]
    }
  },

  "constraint_order": [
    "side_stitches"
  ]
}