excalidraw-convert 0.1.0__tar.gz

excalidraw_convert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lyndon Liang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

excalidraw_convert-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: excalidraw-convert
+Version: 0.1.0
+Summary: Convert Excalidraw diagrams to PowerPoint or Lucid Package Format
+Author: Lyndon Liang
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lliang17/excalidraw-convert
+Project-URL: Issues, https://github.com/lliang17/excalidraw-convert/issues
+Keywords: excalidraw,powerpoint,pptx,diagram,convert
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-pptx>=0.6.21
+Requires-Dist: requests>=2.28.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: Pillow>=10.0.0
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7.0; extra == "svg"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# excalidraw-convert
+
+Convert Excalidraw diagrams to **editable PowerPoint vector objects** or **Lucid Package Format** (`.lucid`).
+
+---
+
+## Features
+
+### PowerPoint output
+
+Each shape, arrow, and text box becomes a native PowerPoint object you can move, resize, recolour, and animate individually — not a flat image.
+
+| Excalidraw element | PowerPoint output |
+|---|---|
+| Rectangle (with/without roundness) | Auto-shape (Rectangle / Rounded Rectangle) |
+| Ellipse | Auto-shape (Oval) |
+| Diamond | Auto-shape (Diamond) |
+| Arrow (2-point) | Straight Connector with arrowheads |
+| Line / Arrow (multi-point) | Freeform path |
+| Freedraw | Freeform path (approximate) |
+| Text (standalone) | Text Box |
+| Text (bound to shape) | Text inside the parent shape |
+| Image (PNG/JPEG/WEBP) | Embedded picture |
+| Image (SVG) | PNG fallback _(requires `cairosvg`)_ |
+| Frame | Separate slide |
+| No frames | Single slide (whole canvas) |
+
+### Lucid output
+
+Produces a `.lucid` file (ZIP archive in [Lucid Package Format](https://lucid.readme.io/docs/overview-si)) that can be opened directly in LucidChart or LucidSpark.
+
+| Excalidraw element | Lucid output |
+|---|---|
+| Rectangle (with/without roundness) | `rectangle` shape |
+| Ellipse | `circle` shape |
+| Diamond | `diamond` shape |
+| Arrow / Line (2-point) | `elbow` line connector |
+| Arrow / Line (multi-point) | `straight` line with intermediate joints |
+| Freedraw | `flexiblePolygon` (downsampled to ≤100 vertices) |
+| Text (standalone) | `text` shape |
+| Text (bound to shape) | Text property on the parent shape |
+| Image | `image` shape with file embedded in the archive |
+| Frame | Separate page |
+| No frames | Single page (whole canvas) |
+
+### Styling carried over (both formats)
+
+Fill colour, stroke colour, stroke width, dashed/dotted strokes, rounded corners, arrowhead types, opacity, background colour, multi-line text, font family, font size, and text alignment.
+
+---
+
+## Installation
+
+```bash
+pip install excalidraw-convert
+```
+
+For SVG image support in PowerPoint output (optional):
+```bash
+pip install "excalidraw-convert[svg]"
+```
+
+To install from source:
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Command line
+
+```bash
+# Convert to PowerPoint
+excalidraw-convert convert "https://excalidraw.com/#json=<id>,<key>" -o output.pptx
+
+# Convert to Lucid Package Format
+excalidraw-convert convert-lucid "https://excalidraw.com/#json=<id>,<key>" -o output.lucid
+
+# From a direct JSON / .excalidraw file URL
+excalidraw-convert convert "https://raw.githubusercontent.com/you/repo/main/diagram.excalidraw" -o output.pptx
+
+# Append slides to an existing presentation
+excalidraw-convert convert "https://..." -o existing.pptx --embed
+
+# Inspect a scene before converting
+excalidraw-convert inspect "https://..."
+```
+
+Also callable as a module:
+```bash
+python -m excalidraw_convert convert "https://..." -o output.pptx
+python -m excalidraw_convert convert-lucid "https://..." -o output.lucid
+```
+
+### Python API
+
+```python
+from excalidraw_convert import fetch_scene, convert, convert_to_lucid
+
+scene = fetch_scene("https://excalidraw.com/#json=<id>,<key>")
+
+# PowerPoint
+convert(scene, "output.pptx")
+
+# Lucid Package Format
+convert_to_lucid(scene, "output.lucid")
+
+# Append to an existing PowerPoint file
+convert(scene, "existing.pptx", embed_path="existing.pptx")
+
+# Custom slide dimensions (inches, new files only)
+convert(scene, "output.pptx", slide_width=10, slide_height=7.5)
+```
+
+---
+
+## Supported URL formats
+
+| Format | Example |
+|---|---|
+| Excalidraw share link | `https://excalidraw.com/#json=abc123,base64key` |
+| Raw `.excalidraw` file URL | `https://raw.githubusercontent.com/.../diagram.excalidraw` |
+| Any URL returning JSON | `https://your-server.com/scene.json` |
+
+> **Note on Excalidraw share links:** the scene is end-to-end encrypted in the browser. This tool replicates the AES-GCM decryption that the Excalidraw web app performs client-side. If decryption fails for a link, try exporting the scene as a `.excalidraw` file and hosting it somewhere accessible.
+
+---
+
+## Limitations / known gaps
+
+### Both formats
+- **Roughness / hand-drawn style**: Excalidraw's sketchy aesthetic is not reproduced — shapes are rendered as clean geometric shapes.
+- **Hachure fill**: approximated as a solid fill.
+- **Curved / elbow arrows**: rendered as straight connectors or straight segments.
+- **`freedraw` pressures**: variable stroke-width pressure data is ignored; a fixed width is used.
+- **Grouped elements**: group membership is preserved in rendering order but not as native groups.
+- **Embeddable / iframe elements**: skipped with a warning.
+- **Fonts**: Excalidraw's *Virgil* hand-drawn font is mapped to *Caveat* (install it for best results; falls back to the system default).
+
+### PowerPoint only
+- `freedraw` elements are rendered as freeform polygon paths (not true brush strokes).
+
+### Lucid only
+- `freedraw` elements are approximated as `flexiblePolygon` shapes with up to 100 sampled vertices.
+- Arrow connection points snap to the nearest edge of the target shape.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

excalidraw_convert-0.1.0/README.md

@@ -0,0 +1,156 @@
+# excalidraw-convert
+
+Convert Excalidraw diagrams to **editable PowerPoint vector objects** or **Lucid Package Format** (`.lucid`).
+
+---
+
+## Features
+
+### PowerPoint output
+
+Each shape, arrow, and text box becomes a native PowerPoint object you can move, resize, recolour, and animate individually — not a flat image.
+
+| Excalidraw element | PowerPoint output |
+|---|---|
+| Rectangle (with/without roundness) | Auto-shape (Rectangle / Rounded Rectangle) |
+| Ellipse | Auto-shape (Oval) |
+| Diamond | Auto-shape (Diamond) |
+| Arrow (2-point) | Straight Connector with arrowheads |
+| Line / Arrow (multi-point) | Freeform path |
+| Freedraw | Freeform path (approximate) |
+| Text (standalone) | Text Box |
+| Text (bound to shape) | Text inside the parent shape |
+| Image (PNG/JPEG/WEBP) | Embedded picture |
+| Image (SVG) | PNG fallback _(requires `cairosvg`)_ |
+| Frame | Separate slide |
+| No frames | Single slide (whole canvas) |
+
+### Lucid output
+
+Produces a `.lucid` file (ZIP archive in [Lucid Package Format](https://lucid.readme.io/docs/overview-si)) that can be opened directly in LucidChart or LucidSpark.
+
+| Excalidraw element | Lucid output |
+|---|---|
+| Rectangle (with/without roundness) | `rectangle` shape |
+| Ellipse | `circle` shape |
+| Diamond | `diamond` shape |
+| Arrow / Line (2-point) | `elbow` line connector |
+| Arrow / Line (multi-point) | `straight` line with intermediate joints |
+| Freedraw | `flexiblePolygon` (downsampled to ≤100 vertices) |
+| Text (standalone) | `text` shape |
+| Text (bound to shape) | Text property on the parent shape |
+| Image | `image` shape with file embedded in the archive |
+| Frame | Separate page |
+| No frames | Single page (whole canvas) |
+
+### Styling carried over (both formats)
+
+Fill colour, stroke colour, stroke width, dashed/dotted strokes, rounded corners, arrowhead types, opacity, background colour, multi-line text, font family, font size, and text alignment.
+
+---
+
+## Installation
+
+```bash
+pip install excalidraw-convert
+```
+
+For SVG image support in PowerPoint output (optional):
+```bash
+pip install "excalidraw-convert[svg]"
+```
+
+To install from source:
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Command line
+
+```bash
+# Convert to PowerPoint
+excalidraw-convert convert "https://excalidraw.com/#json=<id>,<key>" -o output.pptx
+
+# Convert to Lucid Package Format
+excalidraw-convert convert-lucid "https://excalidraw.com/#json=<id>,<key>" -o output.lucid
+
+# From a direct JSON / .excalidraw file URL
+excalidraw-convert convert "https://raw.githubusercontent.com/you/repo/main/diagram.excalidraw" -o output.pptx
+
+# Append slides to an existing presentation
+excalidraw-convert convert "https://..." -o existing.pptx --embed
+
+# Inspect a scene before converting
+excalidraw-convert inspect "https://..."
+```
+
+Also callable as a module:
+```bash
+python -m excalidraw_convert convert "https://..." -o output.pptx
+python -m excalidraw_convert convert-lucid "https://..." -o output.lucid
+```
+
+### Python API
+
+```python
+from excalidraw_convert import fetch_scene, convert, convert_to_lucid
+
+scene = fetch_scene("https://excalidraw.com/#json=<id>,<key>")
+
+# PowerPoint
+convert(scene, "output.pptx")
+
+# Lucid Package Format
+convert_to_lucid(scene, "output.lucid")
+
+# Append to an existing PowerPoint file
+convert(scene, "existing.pptx", embed_path="existing.pptx")
+
+# Custom slide dimensions (inches, new files only)
+convert(scene, "output.pptx", slide_width=10, slide_height=7.5)
+```
+
+---
+
+## Supported URL formats
+
+| Format | Example |
+|---|---|
+| Excalidraw share link | `https://excalidraw.com/#json=abc123,base64key` |
+| Raw `.excalidraw` file URL | `https://raw.githubusercontent.com/.../diagram.excalidraw` |
+| Any URL returning JSON | `https://your-server.com/scene.json` |
+
+> **Note on Excalidraw share links:** the scene is end-to-end encrypted in the browser. This tool replicates the AES-GCM decryption that the Excalidraw web app performs client-side. If decryption fails for a link, try exporting the scene as a `.excalidraw` file and hosting it somewhere accessible.
+
+---
+
+## Limitations / known gaps
+
+### Both formats
+- **Roughness / hand-drawn style**: Excalidraw's sketchy aesthetic is not reproduced — shapes are rendered as clean geometric shapes.
+- **Hachure fill**: approximated as a solid fill.
+- **Curved / elbow arrows**: rendered as straight connectors or straight segments.
+- **`freedraw` pressures**: variable stroke-width pressure data is ignored; a fixed width is used.
+- **Grouped elements**: group membership is preserved in rendering order but not as native groups.
+- **Embeddable / iframe elements**: skipped with a warning.
+- **Fonts**: Excalidraw's *Virgil* hand-drawn font is mapped to *Caveat* (install it for best results; falls back to the system default).
+
+### PowerPoint only
+- `freedraw` elements are rendered as freeform polygon paths (not true brush strokes).
+
+### Lucid only
+- `freedraw` elements are approximated as `flexiblePolygon` shapes with up to 100 sampled vertices.
+- Arrow connection points snap to the nearest edge of the target shape.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

excalidraw_convert-0.1.0/excalidraw_convert/__init__.py

@@ -0,0 +1,11 @@
+"""
+excalidraw-convert: Convert Excalidraw diagrams to editable PowerPoint vector objects
+or Lucid Package Format (.lucid) files.
+"""
+
+from .converter import convert
+from .fetcher import fetch_scene
+from .lucid_converter import convert_to_lucid
+
+__all__ = ["convert", "fetch_scene", "convert_to_lucid"]
+__version__ = "0.1.0"

excalidraw_convert-0.1.0/excalidraw_convert/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

excalidraw_convert-0.1.0/excalidraw_convert/cli.py

@@ -0,0 +1,186 @@
+"""
+CLI interface for excalidraw-convert.
+
+Usage examples:
+    # Convert to PowerPoint
+    excalidraw-convert convert "https://excalidraw.com/#json=abc,key" -o output.pptx
+
+    # Append slides to an existing .pptx
+    excalidraw-convert convert "https://..." -o existing.pptx --embed
+
+    # Convert to Lucid Package Format
+    excalidraw-convert convert-lucid "https://excalidraw.com/#json=abc,key" -o output.lucid
+
+    # Also available as: python -m excalidraw_convert convert "..."
+"""
+
+import sys
+
+import click
+
+from .fetcher import fetch_scene
+from .converter import convert
+from .lucid_converter import convert_to_lucid
+
+
+@click.group()
+@click.version_option(package_name="excalidraw-convert")
+def main():
+    """Convert Excalidraw diagrams to PowerPoint or Lucid Package Format."""
+
+
+@main.command()
+@click.argument("url")
+@click.option(
+    "-o",
+    "--output",
+    default="output.pptx",
+    show_default=True,
+    help="Path of the output .pptx file.",
+)
+@click.option(
+    "--embed",
+    is_flag=True,
+    default=False,
+    help=(
+        "Append the converted slides to an existing file instead of creating "
+        "a new one.  Requires --output to point at an existing .pptx."
+    ),
+)
+@click.option(
+    "--slide-width",
+    default=13.33,
+    show_default=True,
+    type=float,
+    help="Slide width in inches (new presentations only).",
+)
+@click.option(
+    "--slide-height",
+    default=7.5,
+    show_default=True,
+    type=float,
+    help="Slide height in inches (new presentations only).",
+)
+def convert_cmd(url: str, output: str, embed: bool, slide_width: float, slide_height: float):
+    """
+    Convert an Excalidraw diagram at URL to a PowerPoint file.
+
+    URL can be:
+
+    \b
+      • An Excalidraw share link:  https://excalidraw.com/#json=<id>,<key>
+      • A direct JSON/file URL:    https://example.com/diagram.excalidraw
+    """
+    click.echo(f"Fetching scene from: {url}")
+    try:
+        scene = fetch_scene(url)
+    except Exception as exc:
+        click.echo(f"Error fetching scene: {exc}", err=True)
+        sys.exit(1)
+
+    n_elements = len([e for e in scene.get("elements", []) if not e.get("isDeleted")])
+    n_frames = len([e for e in scene.get("elements", []) if e["type"] == "frame" and not e.get("isDeleted")])
+    click.echo(
+        f"Scene loaded: {n_elements} elements, "
+        f"{n_frames} frame(s) -> {max(n_frames, 1)} slide(s)"
+    )
+
+    embed_path = output if embed else None
+
+    try:
+        convert(
+            scene,
+            output_path=output,
+            embed_path=embed_path,
+            slide_width=slide_width,
+            slide_height=slide_height,
+        )
+    except Exception as exc:
+        click.echo(f"Error converting scene: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Saved: {output}")
+
+
+@main.command()
+@click.argument("url")
+def inspect(url: str):
+    """Print a summary of the Excalidraw scene without converting."""
+    click.echo(f"Fetching: {url}")
+    try:
+        scene = fetch_scene(url)
+    except Exception as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    elements = [e for e in scene.get("elements", []) if not e.get("isDeleted")]
+
+    from collections import Counter
+    counts = Counter(e["type"] for e in elements)
+
+    click.echo(f"\nElement counts:")
+    for etype, count in sorted(counts.items()):
+        click.echo(f"  {etype:20s}  {count}")
+
+    frames = [e for e in elements if e["type"] == "frame"]
+    if frames:
+        click.echo(f"\nFrames ({len(frames)}):")
+        for f in frames:
+            click.echo(
+                f"  [{f.get('name', '(unnamed)')}]  "
+                f"{f['width']:.0f}×{f['height']:.0f} px  "
+                f"@ ({f['x']:.0f}, {f['y']:.0f})"
+            )
+    else:
+        click.echo("\nNo frames found — whole canvas will become one slide.")
+
+    files = scene.get("files", {})
+    if files:
+        click.echo(f"\nEmbedded files: {len(files)}")
+
+
+@main.command("convert-lucid")
+@click.argument("url")
+@click.option(
+    "-o",
+    "--output",
+    default="output.lucid",
+    show_default=True,
+    help="Path of the output .lucid file.",
+)
+def convert_lucid_cmd(url: str, output: str):
+    """
+    Convert an Excalidraw diagram at URL to a Lucid Package Format (.lucid) file.
+
+    URL can be:
+
+    \b
+      • An Excalidraw share link:  https://excalidraw.com/#json=<id>,<key>
+      • A direct JSON/file URL:    https://example.com/diagram.excalidraw
+    """
+    click.echo(f"Fetching scene from: {url}")
+    try:
+        scene = fetch_scene(url)
+    except Exception as exc:
+        click.echo(f"Error fetching scene: {exc}", err=True)
+        import sys
+        sys.exit(1)
+
+    n_elements = len([e for e in scene.get("elements", []) if not e.get("isDeleted")])
+    n_frames = len([
+        e for e in scene.get("elements", [])
+        if e["type"] == "frame" and not e.get("isDeleted")
+    ])
+    click.echo(
+        f"Scene loaded: {n_elements} elements, "
+        f"{n_frames} frame(s) → {max(n_frames, 1)} page(s)"
+    )
+
+    try:
+        convert_to_lucid(scene, output_path=output)
+    except Exception as exc:
+        click.echo(f"Error converting scene: {exc}", err=True)
+        import sys
+        sys.exit(1)
+
+    click.echo(f"Saved: {output}")