144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# Artifact Editor
|
|
|
|
**AI-enhanced editor for creating diagrams, sketches, 3D models, and other artifacts from code.**
|
|
|
|
A standalone PyQt6-based editor for creating visual artifacts. Designed to integrate with discussion tools, documentation systems, and IDEs.
|
|
|
|
## Features
|
|
|
|
- **Split-view interface** - Code editor on the left, live preview on the right
|
|
- **Multi-format support** - PlantUML, Mermaid, and OpenSCAD
|
|
- **Elements panel** - View and manage diagram elements
|
|
- **Visual editing** - Add, edit, and delete elements via dialogs
|
|
- **Templates** - Start from pre-built templates for common diagrams
|
|
- **Syntax highlighting** - Format-specific code highlighting
|
|
- **Live preview** - See changes as you type
|
|
- **3D controls** - Rotate/pan OpenSCAD models with mouse
|
|
|
|
## Supported Artifact Types
|
|
|
|
| Type | Description | Features |
|
|
|------|-------------|----------|
|
|
| `plantuml` | UML diagrams (class, sequence, component, etc.) | Element editing, relationships, click-to-select |
|
|
| `mermaid` | Flowcharts, sequence, ER, state diagrams | Node editing with shapes, connections |
|
|
| `openscad` | 3D parametric CAD models | Transform controls (translate/rotate/scale), module insertion |
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Clone and install
|
|
git clone <repo>
|
|
cd artifact-editor
|
|
pip install -e .
|
|
|
|
# Or just install dependencies
|
|
pip install PyQt6
|
|
|
|
# Optional renderers
|
|
sudo apt install plantuml # For PlantUML
|
|
npm install -g @mermaid-js/mermaid-cli # For Mermaid
|
|
sudo apt install openscad # For 3D CAD
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Launch the GUI Editor
|
|
|
|
```bash
|
|
# Launch with default (PlantUML)
|
|
artifact-editor
|
|
|
|
# Launch for specific format
|
|
artifact-editor --type mermaid
|
|
artifact-editor --type openscad
|
|
|
|
# Open existing file
|
|
artifact-editor --type plantuml --initial-file diagram.puml
|
|
```
|
|
|
|
### GUI Features
|
|
|
|
**Elements Panel (right sidebar):**
|
|
- **+Element** - Add new elements (nodes, shapes, primitives)
|
|
- **+Connection** - Add relationships between elements
|
|
- **Double-click** - Edit existing elements in a dialog
|
|
- **Delete** - Remove selected elements
|
|
|
|
**For PlantUML:**
|
|
- Add classes, interfaces, actors, components, etc.
|
|
- Define relationships (inheritance, composition, etc.)
|
|
- Click on elements in the preview to select in code
|
|
|
|
**For Mermaid:**
|
|
- Add flowchart nodes with various shapes (rectangle, diamond, circle, etc.)
|
|
- Add sequence diagram participants
|
|
- Create connections between nodes
|
|
|
|
**For OpenSCAD:**
|
|
- Add 3D primitives (cube, sphere, cylinder)
|
|
- Add 2D shapes (circle, square)
|
|
- Boolean operations (union, difference, intersection)
|
|
- Transform wrappers (translate, rotate, scale)
|
|
- Insert at cursor, end of file, or inside modules
|
|
- 3D preview with mouse rotation
|
|
|
|
## Architecture
|
|
|
|
```
|
|
artifact-editor/
|
|
├── src/artifact_editor/
|
|
│ ├── cli.py # CLI entry point
|
|
│ ├── gui.py # PyQt6 main window
|
|
│ ├── dialogs.py # Element/relationship dialogs
|
|
│ ├── parser.py # PlantUML parser
|
|
│ ├── mermaid_parser.py # Mermaid parser
|
|
│ ├── openscad_parser.py # OpenSCAD parser
|
|
│ ├── templates.py # Diagram templates
|
|
│ └── renderers/ # Convert source to visual output
|
|
│ ├── plantuml.py
|
|
│ ├── mermaid.py
|
|
│ └── openscad.py
|
|
```
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
- **Ctrl+S** - Save file
|
|
- **Ctrl+Z** - Undo
|
|
- **Ctrl+Y** - Redo
|
|
- **Ctrl+Mouse wheel** - Zoom preview
|
|
|
|
## Integration
|
|
|
|
The editor can be launched from other applications:
|
|
|
|
```bash
|
|
# Launch and specify output
|
|
artifact-editor --type TYPE --output /path/to/output.svg
|
|
|
|
# Exit codes:
|
|
# 0 - Saved successfully (stdout: "ARTIFACT_SAVED:/path/to/output.svg")
|
|
# 1 - Cancelled by user
|
|
# 2 - Error (stderr: error message)
|
|
```
|
|
|
|
Example Python integration:
|
|
```python
|
|
import subprocess
|
|
|
|
result = subprocess.run([
|
|
"artifact-editor",
|
|
"--type", "mermaid",
|
|
"--output", "/tmp/diagram.svg",
|
|
], capture_output=True, text=True)
|
|
|
|
if result.returncode == 0:
|
|
for line in result.stdout.split('\n'):
|
|
if line.startswith("ARTIFACT_SAVED:"):
|
|
artifact_path = line.split(":", 1)[1]
|
|
print(f"Created: {artifact_path}")
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|