Home

Welcome to the drawmate wiki!

🧩 API Reference

This document outlines the Multi-Connection JSON API used to define topologies in drawmate, as well as the command-line interface for rendering and template building.

---

🚀 Command-Line Usage

drawmate is operated via its main script (soon will be installable via pip):

• Note: until I have dsitrubuted wheels you will have to build from source. See BUILD.md in the docs directory for detailed instructions.
• In the future, you will pip install drawmate and just run

drawmate [input-file] [output-file]

• You are also free to use the legacy branch if you want to run the script without building from source, however, this version is no longer maintained and may lack functionality.

python main.py [input_file] [output_file] [options]

Arguments:

• input_file: Path to your input JSON template.
• output_file: Path where the rendered output (e.g., XML) will be saved.

Options:

• -v, --version
  Print drawmate version and system information.

• -b, --build-template
  Launch an interactive guide to build a starter JSON template.

---

🔄 Multi-Connection JSON Format

drawmate now exclusively supports multi-connection mode. Each node can map to multiple matrix ports using indexed routing logic. You can still draw single connection nodes, but the multi-connection JSON format must be used. See README.md or below for examples.

Example Node Definition

"first-level-left": {
  "labels": [
    [
      "AV Appliance",
      ["HDMI", "HDMI"],        // Input port labels (left side)
      ["HDMI", "HDMI"],        // Output port labels (right side)
      [0, 1],                  // Matrix indexes to connect FROM (left side)
      [0, 1]                 // Matrix indexes to connect TO (right side)
    ],
    [
      "__SPAN__",
      "",
      "",
      ["NONE"],
      ["NONE"]
    ],
      "AV Appliance", // Single connection node
      "HDMI",
      "HDMI",
      ["NONE"],
      ["NONE"]
  ]
}

🔹 Key Behavior

• The array [0, 1] defines the port positions this node occupies vertically relative to the matrix.
• __SPAN__ must be placed directly beneath any multi-connection node to define a visual gap where the node expands across ports.
• "NONE" (in all caps) is used to as a placeholder, and the engine will infer an adjacent connection. In the future, you will be able to specify specific indexes/ports via the index system.
• All nodes must use this structure, even if only connecting to a single port.

---

⚠️ Notes

• You must:
  • Include __SPAN__ under any node that spans more than one port.
• Legacy fields like matrices, graph-dimensions, and connections-left/right remain unchanged.

---

🧪 Templates & Testing

Predefined example templates are located in:

drawmate/test_templates/

These include:

• Valid multi-connection node layouts
• Proper use of __SPAN__
• Left/right matrix variations
• Hybrid node configurations

Feel free to duplicate and modify these templates for your own use.

---

✅ Summary

Mode	Supports Multiple Ports	Requires __SPAN__	Requires Indexing	Backward Compatible
Multi-Connection	✅	✅	✅	✅ (with updated format)

---

ℹ️ Version & System Info

To print version and system info, run:

python main.py --version