Content
# Scientific Illustrator
[English guide](#english-guide) · [MIT License](LICENSE)
A plugin that enables Codex to progressively draw, replicate, review, and correct scientific illustrations in **Microsoft PowerPoint or draw.io desktop**. The goal is not to paste the reference image as a whole, but to restore it as editable text, shapes, connectors, tables, charts, and atomic images.
> **Project relationship: This project is an integrated upgrade and optimization of the previous research project [`icebird1998/drawio-scientific-illustrator`](https://github.com/icebird1998/drawio-scientific-illustrator).** The predecessor project focused on draw.io; this project retains and upgrades draw.io capabilities while adding PowerPoint native object control and letting both software follow the same design, drawing, review, correction, and editable acceptance criteria.
**Developer: Scientific Upmain: JP**<br>
GitHub: [@icebird1998](https://github.com/icebird1998)
> Current version: `1.3.0`. PowerPoint real-time control is for Windows desktop Microsoft PowerPoint; draw.io supports Windows and includes executable file discovery logic for macOS/Linux, with actual performance affected by draw.io/Electron packaging.
## English Guide
### What Problem Does This Project Solve
Ordinary "image to PPT / draw.io" often results in a flat image or only redraws a few outlines. Scientific Illustrator takes "maximum editability" as a hard constraint:
- Text must use native text objects first, not baked into images;
- Rectangles, circles, partitions, legends, annotations, and arrows use native shapes and connectors;
- Tables and charts use native tables, native charts, or editable combined objects;
- Only areas that cannot be reliably expressed with target software native primitives allow illustrations;
- Illustrations must be cropped into semantically single "atomic images," not covering separable text and shapes with a large image;
- Each panel completes a structural check and rendering check, correcting issues before drawing the next area;
- The entire image completes a review, correction, and re-examination until the reviewer has no reproducible blocking issues.
### Upgraded from Previous Research Project
| Project | Previous Research Project | Scientific Illustrator |
|---|---|---|
| Target Software | draw.io | PowerPoint + draw.io |
| Drawing Strategy | draw.io real-time graph model | Dual-backend unified semantics, separate native object mapping |
| Role Process | Redraw and check | Designer → Drawer → Reviewer → Corrector closed loop |
| Editability | Prioritize draw.io primitives | Deep editability audit + atomic grid constraints |
| Layout | Gradual drawing and adjustment | Alignment, equal distance, partition grid, connector safe spacing |
| Quality Gate | Screenshot check | Local structure + local rendering + full image structure + full image rendering |
| No Reference Design | Basic support | Design layout and connection routing first, then execute by panel |
The new project is not just adding an independent logic to PowerPoint. Both draw.io and PowerPoint must detect capabilities, build region by region, maintain deep editability, execute the same review criteria, and deliver their respective native files.
### Dual-Backend Capability Comparison
| Unified Capability | PowerPoint Implementation | draw.io Implementation |
|---|---|---|
| Status and Connection | Current PowerPoint application, presentation, and slide | Visible draw.io desktop canvas and graph status |
| Capability Detection | Enumerate available shapes, connectors, tables, charts, images, combinations, and layout operations | Enumerate available cell, edge, tables, charts, images, combinations, and layout operations |
| Text and Basic Graphics | Native text box, AutoShape | Native vertex and HTML/text label |
| Lines and Arrows | Native line/connector, connection points, and arrow endpoints | Native line/edge, orthogonal routing, and endpoint styles |
| Tables | PowerPoint native Table | Editable cell combined table |
| Charts | PowerPoint native Chart | Editable combined chart |
| Images | Image object, cropping, and position control | Image cell, cropped atomic material |
| Structural Operations | Naming, copying, grouping, ungrouping, hierarchy, alignment, equal distance | Cell ID, copying, grouping, ungrouping, hierarchy, alignment, equal distance |
| Review | Structural check + slide export image | Graph check + canvas screenshot |
| Delivery | `.pptx` + slide preview image | `.drawio` + PNG/SVG/PDF/JPG |
The implementation objects differ, but the semantic results, editability requirements, and pass thresholds are the same. Users only need to choose PowerPoint or draw.io, and the plugin will automatically select and arrange the required Skill without manually specifying `$skill-name`.
### Four-Role Quality Closed Loop
1. **Designer**: When there is a reference image, first decompose panels, objects, hierarchy, spacing, and connection relationships; when there is no reference image, first establish visual grammar, grid, and routing scheme.
2. **Drawer**: Detect target software capabilities, prioritize native editable objects, and draw step by step by panel or logical area.
3. **Reviewer**: Simultaneously check visual consistency and deep editability, including text typography, margins, alignment, arrow clearance, hierarchy, grouping, and whether images can still be disassembled.
4. **Corrector**: Convert issues into minimal, executable, object-level modification instructions and return them to the drawer for execution.
Each local execution of `drawing → structural check → rendering check → review → correction → re-check`. After the entire image is completed, execute the same overall cycle. A successful MCP call does not equal qualified drawing; it must be judged by object structure and actual rendering results.
### System Requirements
#### General
1. Codex desktop application or Codex CLI that supports plugins;
2. Git;
3. When launching MCP from outside the Codex bundled runtime environment, a usable Node.js is required, and Node.js 22 or higher is recommended;
4. Restart Codex after installation and create a new task to load the new Skill and MCP tool.
#### PowerPoint
- Windows;
- Microsoft PowerPoint desktop version;
- PowerPoint should not be in a modal dialog, protected view, or blocked by other operations;
- The plugin controls PowerPoint through the local PowerShell and Office COM object model, without using system mouse and keyboard simulation.
#### draw.io
- [draw.io Desktop](https://www.drawio.com/);
- Windows is the primary test platform; macOS/Linux is supported as much as possible;
- The plugin calls draw.io's own graph API through a local debugging channel, without generating XML to pretend to draw in real-time.
### Installation
#### Method 1: Let Codex Install
Paste in a Codex task with terminal permissions:
```text
Please install the public Codex plugin: https://github.com/icebird1998/scientific-illustrator.
Clone the repository to local, register the repository root as Codex Marketplace, and install scientific-illustrator@scientific-illustrator-tools.
Tell me when to restart Codex.
```
#### Method 2: Windows One-Click Installation
Check [`install.ps1`](install.ps1) first, then run:
```powershell
$p="$env:TEMP\scientific-illustrator-install.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/icebird1998/scientific-illustrator/main/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p
```
#### Method 3: macOS/Linux One-Click Installation
This method can install draw.io capabilities; PowerPoint real-time control still requires Windows:
```bash
curl -fsSL https://raw.githubusercontent.com/icebird1998/scientific-illustrator/main/install.sh | bash
```
#### Method 4: Manual, Auditable Installation
PowerShell:
```powershell
git clone https://github.com/icebird1998/scientific-illustrator.git
Set-Location scientific-illustrator
codex plugin marketplace add (Get-Location).Path
codex plugin add scientific-illustrator@scientific-illustrator-tools
```
macOS/Linux:
```bash
git clone https://github.com/icebird1998/scientific-illustrator.git
cd scientific-illustrator
codex plugin marketplace add "$(pwd)"
codex plugin add scientific-illustrator@scientific-illustrator-tools
```
Please restart Codex and create a new task after installation. Complex reference images are recommended to use models with strong visual understanding and reasoning capabilities and reserve enough time for multi-round local review.
### Migration from Old Project
The old project will be retained and not covered by this project. Since both plugins contain draw.io tools, it is recommended to disable or uninstall `drawio-scientific-illustrator` in Codex plugin settings during migration, then enable `scientific-illustrator` to avoid duplicate tool selection ambiguity. After confirming the new project works normally, delete the old project's local clone.
### How to Call: Skill Automatic Selection
Select the **Scientific Illustrator** plugin in the Codex input box or use it in an environment that supports plugin links:
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
```
Then, just tell the plugin:
1. Use PowerPoint or draw.io;
2. Replicate a reference image, design without a reference image, check an existing illustration, or correct issues;
3. Output path, image ratio, language, or journal style constraints.
The plugin will automatically select design, replication, drawing, review, and correction Skills based on the task. Do not manually list Skills in the prompt unless you want to force a specific stage.
> `@personal` is a plugin link installed by the personal Marketplace. If you install it from this repository's Marketplace and the plugin appears under another source, directly select **Scientific Illustrator** in the Codex input box; the main prompt remains unchanged.
### PowerPoint Prompt
#### With Reference Image: Maximum Editability Replication
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Use the plugin to replicate the reference image you uploaded in PowerPoint. First, connect to the current PowerPoint, call status, capability detection, and structural inspection tools; if there is no presentation, create a new one. Prioritize native editable PowerPoint text, shapes, connectors, tables, and charts. Only allow image insertion for minimal semantic areas that cannot be reliably expressed with native objects, and continue to check if it can be further disassembled. Draw step by step by panel, perform structural checks and export image visual checks for each completed local area, correct issues before drawing the next area, and particularly check text position, alignment, equal distance, arrow endpoint clearance with rectangle boundary, hierarchy, and deep editability. After completing the entire image, review and correct repeatedly until the reviewer has no reproducible blocking issues, then save as PPTX and export the final slide preview image.
```
#### Without Reference Image: Design from Research Content
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Design an editable scientific summary image in PowerPoint based on the research content below. First, plan the information hierarchy, panel grid, visual grammar, and arrow channels, then start drawing. Use native PowerPoint objects for text, shapes, tables, charts, and connectors; unify font, line width, rounded corners, spacing, and color. Check layout and editability for each completed panel and correct issues, then perform a full-image review. Ensure no overlap, no text overflow, and neatly arranged arrows before saving. Research content: …
```
#### Read-Only Check Current PowerPoint
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Connect to the current PowerPoint, call status, capability detection, and inspection tools, and only read the presentation structure without making modifications. Report the current page size, number of slides, object types, naming, hierarchy, text, combination relationships, and potential editability issues.
```
### draw.io Prompt
#### With Reference Image: Maximum Editability Replication
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Use the plugin to replicate the reference image you uploaded in the visible draw.io desktop canvas. First, launch or connect to draw.io, call status, capability detection, and structural inspection tools. Prioritize native editable text, vertex, edge, combined tables, and combined charts; only allow atomic image insertion for minimal semantic areas that cannot be reliably expressed with native primitives. Draw step by step by panel, inspect graph structure, and capture a real canvas visual review for each completed local area. Correct issues before continuing, particularly check alignment, equal distance, text wrapping, orthogonal arrow routing, endpoint clearance, hierarchy, combination relationships, and whether images can still be disassembled. After completing the entire image, review and correct repeatedly until there are no reproducible blocking issues, then save .drawio, validate the file, and export 2000 px PNG and SVG.
```
#### Without Reference Image: Design from Research Content
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Design an editable research flowchart in draw.io based on the research content below. First, plan the reading direction, panel grid, node size, and independent arrow channels, then start drawing. Use consistent styles for repeated nodes and precise alignment and equal distance; prioritize orthogonal routing for connectors, avoiding node or text intersection. Check and correct screenshot issues for each completed area, then perform a full-image structure and rendering review. Save .drawio and export PNG and SVG after passing. Research content: …
```
#### Read-Only Check Current draw.io
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
Connect to the current visible draw.io canvas, call status, capability detection, structural inspection, and screenshot tools, and only read the current graph without modifications. Report page, object, connection relationships, grouping, hierarchy, text, layout, and deep editability issues.
```
### Typical Tool Process
PowerPoint usually executes:
```text
powerpoint_status
→ powerpoint_get_capabilities
→ powerpoint_new_presentation (only when needed)
→ powerpoint_inspect
→ Add native objects by panel
→ powerpoint_audit_figure + powerpoint_export_slide_image
→ Review / correction / re-check
→ powerpoint_save
```
draw.io usually executes:
```text
drawio_live_launch
→ drawio_live_status
→ drawio_live_get_capabilities
→ drawio_live_inspect
→ Add native cell/edge/editable combined objects by region
→ drawio_live_audit_figure + drawio_live_screenshot
→ Review / correction / re-check
→ drawio_live_save_snapshot
→ drawio_validate + drawio_export
```
These sequences are quality protocols, not requiring users to manually call each tool. The plugin will automatically execute based on the current task and read/write permissions.
### Update
Run the corresponding one-click installation script again. The installer will perform a safe fast-forward update on the existing repository and reinstall the plugin. You can also manually execute:
```powershell
git -C "$HOME\.codex\marketplaces\scientific-illustrator" pull --ff-only
codex plugin add scientific-illustrator@scientific-illustrator-tools
```
Restart Codex and create a new task after updating.
### draw.io Optional Configuration
| Environment Variable | Effect | Default Value |
|---|---|---|
| `DRAWIO_PATH` | Explicitly specify draw.io executable file | Auto-detection |
| `DRAWIO_LIVE_PORT` | Preferred local debugging port | `9333`, choose nearby free port on conflict |
| `DRAWIO_LIVE_PROFILE` | draw.io/Electron independent user directory | `~/.drawio-live-mcp/<port>` |
PowerShell example:
```powershell
$env:DRAWIO_PATH = "D:\Apps\draw.io\draw.io.exe"
```
PowerPoint does not require network port configuration; it uses the local Office COM. If the connection fails, close PowerPoint's pop-ups or protected view and retry status checks.
### Frequently Asked Questions
- **Plugin not visible after installation**: Restart Codex and create a new task; old tasks will not load new tools automatically.
- **`node` not available**: Install Node.js 22+, or confirm the Codex bundled runtime environment is available for the plugin.
- **PowerPoint connection failed**: Confirm using Windows desktop PowerPoint and close modal dialogs, protected view, or blocked presentations.
- **draw.io not found**: Install the desktop version or set `DRAWIO_PATH`.
- **draw.io graph not ready**: Close the draw.io window that was previously launched but has failed, then retry.
- **Old plugin and new plugin appear simultaneously**: Disable the old `drawio-scientific-illustrator` and keep only the new plugin.
- **Arrow pressing rectangle**: Require review of connector endpoint clearance with rectangle boundary and have the corrector provide object-level routing adjustments; do not use screenshots to cover.
- **Text position or line break inconsistent**: Check text box margins, font, size, paragraph alignment, line spacing, and boundary box; do not move the entire image.
- **Image can still be disassembled**: Require deep editability review; rebuild text, icons, lines, and arrows into native objects, keeping only minimal atomic images.
- **Export failed**: Confirm the target directory is writable and verify PowerPoint/draw.io desktop can manually save to the same directory.
### Project Structure
```text
scientific-illustrator/
├─ .agents/plugins/marketplace.json
├─ plugins/scientific-illustrator/
│ ├─ .codex-plugin/plugin.json
│ ├─ .mcp.json
│ ├─ scripts/
│ │ ├─ live-server.mjs # draw.io Live MCP
│ │ ├─ server.mjs # draw.io File Check and Export MCP
│ │ ├─ powerpoint-server.mjs # PowerPoint MCP
│ │ └─ powerpoint-bridge.ps1 # PowerPoint COM Bridge
│ └─ skills/ # Design, Cross-Platform Drawing, Review, and Correction Process
├─ scripts/ # Repository Validation and MCP Smoke Test
├─ install.ps1
└─ install.sh
```
### Security and Privacy
- draw.io debug endpoints are bound to `127.0.0.1`;
- PowerPoint uses local COM, no public service exposed;
- No system-level mouse and keyboard automation;
- The plugin does not include telemetry or hosted backends;
- Whether reference images and documents enter the model context depends on Codex and model provider settings, see [PRIVACY.md](PRIVACY.md) for details;
- Verify script content and destination before executing remote installation scripts.
### Known Limitations
- PowerPoint live control depends on Windows and desktop Microsoft PowerPoint;
- Microscopic images, complex textures, heatmaps, and other continuous raster content cannot be losslessly converted to native vector objects; the plugin will limit them to the smallest semantic region;
- Reference image resolution, font availability, and target software rendering differences affect pixel-level consistency;
- "Reviewer has no issues" means passing within the current evidence, threshold, and reproducible check scope, not absolute consistency in a mathematical sense.
---
## English guide
### Overview
Scientific Illustrator is a Codex plugin for building, recreating, reviewing, and correcting scientific figures live in either Microsoft PowerPoint or draw.io Desktop. It prioritizes native editable objects over flattened screenshots.
This project is the **integrated, upgraded, and optimized successor** to [`icebird1998/drawio-scientific-illustrator`](https://github.com/icebird1998/drawio-scientific-illustrator). It preserves and expands the draw.io implementation, adds native PowerPoint control, and applies one shared quality contract to both backends.
**Developer: Scientific Illustrator**<br>
GitHub: [@icebird1998](https://github.com/icebird1998)
### Core behavior
- The user chooses PowerPoint or draw.io; the plugin automatically selects the required skills.
- The Designer establishes structure, layout, visual grammar, and connector lanes.
- The Drawer inventories backend capabilities and creates native editable objects panel by panel.
- The Reviewer checks rendered fidelity, layout, connector clearance, text fit, structure, and deep editability.
- The Corrector translates findings into minimal object-level repairs.
- Local review gates run after each region, followed by repeated whole-figure review.
- Raster images are allowed only for the smallest region that cannot be reproduced reliably with native objects.
PowerPoint uses native text boxes, AutoShapes, connectors, tables, charts, groups, and pictures through the Windows Office COM model. draw.io uses native graph cells, edges, editable table/chart composites, groups, and image cells through draw.io's graph API. The representations differ; the expected semantic result and acceptance gate do not.
### Requirements
1. Codex desktop or Codex CLI with plugin support;
2. Git;
3. Node.js 22+ when the bundled Codex runtime is not available;
4. For PowerPoint: Windows and desktop Microsoft PowerPoint;
5. For draw.io: [draw.io Desktop](https://www.drawio.com/).
Restart Codex and open a new task after installation.
### Install
Ask Codex to install the plugin:
```text
Install the public Codex plugin from https://github.com/icebird1998/scientific-illustrator.
Clone the repository, register its root as a Codex marketplace, install
scientific-illustrator@scientific-illustrator-tools, and tell me when to restart Codex.
```
Windows one-command installer (review [`install.ps1`](install.ps1) first):
```powershell
$p="$env:TEMP\scientific-illustrator-install.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/icebird1998/scientific-illustrator/main/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p
```
macOS/Linux installer for draw.io support (PowerPoint live control still requires Windows):
```bash
curl -fsSL https://raw.githubusercontent.com/icebird1998/scientific-illustrator/main/install.sh | bash
```
Manual installation:
```bash
git clone https://github.com/icebird1998/scientific-illustrator.git
cd scientific-illustrator
codex plugin marketplace add "$(pwd)"
codex plugin add scientific-illustrator@scientific-illustrator-tools
```
On PowerShell, replace `"$(pwd)"` with `(Get-Location).Path`.
### Prompting
Select **Scientific Illustrator** in the Codex composer. In environments that support plugin links, you may start with:
```text
[@scientific-illustrator](plugin://scientific-illustrator@personal)
```
You only need to state the target application and task. Skills are selected automatically.
PowerPoint reference-recreation prompt:
```text
Use Scientific Illustrator in PowerPoint to recreate the attached reference as a maximally
editable figure. Inspect status, capabilities, and presentation structure first. Prefer native
text, shapes, connectors, tables, and charts; use only minimal atomic raster regions when native
objects cannot reproduce the content. Draw panel by panel. After each panel, inspect structure and
export a slide image for visual review, correct all reproducible issues, then continue. Repeat the
whole-slide review until there are no blocking findings, save the PPTX, and export a final preview.
```
draw.io reference-recreation prompt:
```text
Use Scientific Illustrator in the visible draw.io Desktop canvas to recreate the attached
reference as a maximally editable figure. Inspect status, capabilities, and graph structure first.
Prefer native text, vertices, edges, editable table/chart composites, and groups; use only minimal
atomic raster regions when necessary. Draw region by region, inspect the graph and screenshot each
completed region, correct all reproducible issues, then continue. Repeat whole-figure review, save
the .drawio file, validate it, and export PNG and SVG deliverables.
```
Read-only PowerPoint prompt:
```text
Connect to the current PowerPoint presentation. Call status, capability, and inspection tools.
Read only the presentation structure and report it; do not modify anything.
```
The full guide includes no-reference design prompts, read-only draw.io inspection, update instructions, migration advice, configuration, troubleshooting, and the exact backend tool flows.
### Updating
Run the installer again. It performs a fast-forward update and reinstalls the plugin. Restart Codex and create a new task afterward.
If the earlier `drawio-scientific-illustrator` plugin is still enabled, disable or uninstall it before using this successor so duplicate draw.io tools do not create ambiguity.
### Contributing
Issues and pull requests are welcome. Include the operating system, Codex version, PowerPoint or draw.io version, reproduction steps, and relevant MCP error text. Do not upload confidential figures or unpublished data.
## License
MIT © 2026 Scientific Illustrator ([icebird1998](https://github.com/icebird1998))
Connection Info
You Might Also Like
No recommendations available