edrawmax-diagrams-skill

KO | EN

gitlite — search

#javascript #python #hacktoberfest #llm #android #deep-learning #linux #docker #macos #windows #awesome-list #security #ios #open-source

edrawmax-diagrams-skill

(★ 13)

AI skill to design EdrawMax diagrams and auditing it using LLM agents. Note: The skill requires PAID EdrawMax to be installed. The skill is independent from Wondershare AI skills and self-made by AI skill creator based on strict tested rules.

edrawmax-diagrams-skill Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# EdrawMax Diagrams AI Skill (`edrawmax-diagrams`)

> An **AI Agent Skill** and programmatic Python engine for AI assistants (Antigravity IDE, Gemini, etc.) to author, inspect, audit, and batch-generate native, fully editable Wondershare EdrawMax (`.eddx`) diagrams from declarative JSON specifications.

---

## 🤖 About This AI Skill

This repository is packaged as a ready-to-use **AI Agent Skill** (defined in [`SKILL.md`](SKILL.md)). It empowers AI agents to generate professional, native EdrawMax diagrams automatically without needing manual GUI interaction.

### How AI Agents Use This Skill:
- **Natural Language → Native `.eddx`**: When a user requests a Data Flow Diagram (DFD), Use Case diagram, or Activity diagram, the AI agent authors a JSON spec and compiles it directly into an `.eddx` file.
- **Conversion & Batch Generation**: Converts text diagrams (Mermaid, PlantUML, Visio `.vsdx`) into native EdrawMax diagrams for SRS documents, theses, or system design specifications.
- **Template-Based XML cloning**: The AI agent never has to write raw XML geometry; the engine clones real shapes directly from live reference `.eddx` templates.

---

## 🌟 Overview

Drawing dozens of software architecture or systems analysis diagrams manually in **EdrawMax** is slow, and modifying them later (e.g., updating a process name or rerouting flows) is tedious.

This skill treats diagrams as **declarative code**. Diagrams are written as structured **JSON specifications** that can be version-controlled with Git, validated, and programmatically compiled in seconds into native `.eddx` files.

### Why this approach works:
- **No hardcoded XML geometry**: Instead of manually building complex SVG/XML geometry, this tool uses reference `.eddx` template files as **live shape libraries**. Shape XML elements are cloned directly from EdrawMax itself, preserving original formatting, control points, formulas (`F`), and shape numbers.
- **True Connector Glue**: Connectors are bound to shape connection points (`CPoints`) and indexed in the internal `<Connects>` table. When you open the generated `.eddx` file in EdrawMax, arrows move dynamically with shapes when dragged.
- **Smart Orthogonal Router**: An integrated A* + simple-path routing engine navigates connectors around shapes, handles line jumping (bridges), prevents overlap, and aligns flow labels with clean text clipping.
- **Multiple Layout Modes**: Dedicated auto-layout engines (Radial for DFDs, Swimlane for Activity diagrams, Usecase layouts, Column grids) or manual `x,y` coordinate overrides.

---

## 🚀 Supported Diagram Types

| Diagram Type | Spec / Template Key | Layout Engine | Supported Elements |
|---|---|---|---|
| **Data Flow Diagram (DFD)** | `dfd` | `radial` | Processes (Gane-Sarson `P1`), Data Stores (`D1`), External Entities (`E1`), Sister Entities (`P3:`), System Boundaries, Duplicated Satellites |
| **Use Case Diagram** | `usecase` | `usecase` | Actors, Use Cases, System Boundaries, Associations, Extend / Include relations |
| **Activity Diagram** | `activity` | `swimlane` | Start/End States, Actions/States, Decision Diamonds, Vertical Swimlanes |

---

## 📁 Repository Structure

```
.
├── SKILL.md                      # Antigravity AI Agent Skill definition
├── README.md                     # Project documentation (this file)
├── scripts/
│   ├── eddx_gen.py               # Core Generator: JSON Spec → Native .eddx
│   ├── router.py                 # Orthogonal A* Router & lane collision solver
│   ├── eddx_audit.py             # Quantitative layout quality auditor (intersections, collisions)
│   ├── eddx_preview.py           # Fast SVG rendering engine for quick visual inspection
│   ├── uml_audit.py              # Pre-generation validator against UML 2.5 rules
│   ├── eddx_inspect.py           # Reverse-engineering tool for extracting shapes from .eddx
│   └── progress.py              # Build metrics & tracking helper
├── assets/
│   └── templates/                # Live .eddx template files & default JSON specs
│       ├── dfd.eddx / dfd.json
│       ├── usecase.eddx / usecase.json
│       └── activity.eddx / activity.json
└── references/
    ├── eddx-format.md            # Reverse-engineered structure of the .eddx ZIP/XML format
    └── dfd.md                    # Gane & Sarson DFD rules, level balancing, & guidelines
```

---

## ⚙️ Installation & Requirements

- **Python 3.8+**
- **Dependencies**: Standard Python library only (`xml.etree.ElementTree`, `zipfile`, `json`, `math`, `heapq`, `argparse`). No third-party package installation required for core `.eddx` generation!

---

## 💻 Quick Start & Usage

### 1. Generating an `.eddx` File from a JSON Spec

Run `eddx_gen.py` providing a JSON spec file and your target `.eddx` output path:

```bash
python scripts/eddx_gen.py path/to/spec.json -o output.eddx
```

Optionally specify a custom template descriptor:

```bash
python scripts/eddx_gen.py path/to/spec.json -o output.eddx -t assets/templates/dfd.json
```

### 2. Rendering a Quick SVG Preview

Check your diagram layout visually without opening EdrawMax:

```bash
python scripts/eddx_preview.py output.eddx -o preview.svg
```

### 3. Running Layout Quality Audit

Evaluate layout quality metrics (collisions, overlapping lines, label intersections, elbow counts):

```bash
python scripts/eddx_audit.py output.eddx
```

### 4. Validating UML Specs

Ensure your specification complies with UML 2.5 standards before generating:

```bash
python scripts/uml_audit.py path/to/spec.json
```

---

## 📝 Example JSON Specification

Here is an example specification for a **Data Flow Diagram (DFD Level 1)**:

```json
{
  "diagram": "dfd",
  "title": "A-P3 — Questionnaire Processing & Estimation",
  "layout": {
    "mode": "radial",
    "margin": 90,
    "col_gap": 215,
    "row_gap": 70,
    "duplicate": {
      "min_degree": 3,
      "types": ["store", "external"]
    }
  },
  "nodes": [
    {"id": "E1",  "type": "external", "num": "A-E1",   "label": "Applicant"},
    {"id": "P1",  "type": "process",  "num": "A-P3.1", "label": "Display Questionnaire Step"},
    {"id": "P2",  "type": "process",  "num": "A-P3.2", "label": "Calculate Cost Estimate"},
    {"id": "D5",  "type": "store",    "num": "A-D5",   "label": "Question Bank"},
    {"id": "N1",  "type": "entity",   "label": "A-P4: Billing & Collection"},
    {"id": "BND", "type": "boundary", "label": "A-P3 Boundary", "members": ["P1", "P2"]}
  ],
  "flows": [
    {"from": "E1", "to": "P1", "label": "Project & Building Details"},
    {"from": "D5", "to": "P1", "label": "Questions List"},
    {"from": "P1", "to": "P2", "label": "Responses Data"},
    {"from": "P2", "to": "N1", "label": "Approved Estimate"}
  ]
}
```

### Key Spec Properties:
- `diagram`: Template type (`dfd`, `usecase`, `activity`).
- `nodes`: List of diagram elements.
  - `id`: Internal unique key for connecting flows (not displayed).
  - `num`: Element identifier tag (e.g. process number `A-P3.1`).
  - `label`: Main display text (supports UTF-8, Arabic, English, multi-line).
  - `x`, `y` *(optional)*: Manual absolute coordinates if auto-layout is not desired.
- `flows` / `edges`: Connectors between node IDs.
  - `from` / `to`: Source and target node IDs.
  - `label` *(optional)*: Connector label text.
  - `bidir`: `true` for bidirectional arrows.
  - `no_jump`: `true` to skip line-bridge curves on intersection.

---

## 🛠 Advanced Features & Architecture

### 🔄 Radial Layout for DFDs
In DFDs, processing flows primarily between processes while external entities and data stores connect to one or two processes. The `radial` layout engine:
1. Places the process chain linearly along the central axis (horizontal or vertical based on diagram aspect ratio).
2. Distributes external entities and data stores around an enclosing ellipse directly opposite the processes they serve.
3. Automatically snaps satellite items adjacent to their main process, reducing line crossings dramatically (observed reduction from 166 to 27 intersections on complex enterprise DFDs).

### 🛣 Orthogonal Routing Engine (`router.py`)
- Evaluates candidate paths (L-shaped, Z-shaped, and A* grid paths) using a cost function balancing:
  $$\text{Cost} = \text{Intersections} \times C_{\text{cross}} + \text{Turns} \times C_{\text{turn}} + \text{Overlays} \times \infty + \text{Length}$$
- **Detour Limiter**: Prevents unrealistic 1000px detours around minor intersections.
- **Label Clipping**: Renders text blocks with explicit white background fill masks (`BkColor="#ffffff"`) to cleanly clip flow lines behind labels.

### 📄 Print & Page Setup (`PrintSetup`)
Rather than scaling down text to unreadable small fonts to force A4 compliance, `eddx_gen.py` maintains optimal 1:1 readable font sizes and configures native `.eddx` `PrintSetup` with `FittoSheet="TRUE"`. This ensures the diagram exports cleanly to a single A4 PDF page without compromising editing readability in EdrawMax.

---

## 🔍 Extending & Adding New Templates

To add a new diagram type (e.g., Sequence Diagram or ERD):
1. Create a representative diagram in EdrawMax and save it as `assets/templates/your_type.eddx`.
2. Run `eddx_inspect.py` to extract shape definitions and CPoints:
   ```bash
   python scripts/eddx_inspect.py assets/templates/your_type.eddx
   ```
3. Create a corresponding template JSON descriptor (`assets/templates/your_type.json`) mapping node types to shape IDs.

For full technical specifications of the `.eddx` file format (ZIP archive layout, formula syntax, transform properties, `ConPoints`, and `<Connects>` tables), see [`references/eddx-format.md`](references/eddx-format.md).

---

## 📖 Related References

- [EDDX Format Specification](references/eddx-format.md) — Reverse-engineered XML & ZIP structure details.
- [DFD Gane & Sarson Rules](references/dfd.md) — Conventions, balancing rules, and level decomposition standards.
- [Antigravity Skill Definition](SKILL.md) — Detailed AI instructions for `edrawmax-diagrams`.

---

## 📄 License

MIT / Open Source — feel free to use, extend, and integrate into your documentation pipelines.

edrawmax-diagrams-skill

edrawmax-diagrams-skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

edrawmax-diagrams-skill

edrawmax-diagrams-skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README