# Visiomaster's Codex install line still contains a placeholder owner, and its render stage needs Visio itself

> A Windows-first toolkit that rebuilds flowcharts, architecture diagrams and paper figures from images into editable Visio drawings, driven by a scene.json intermediate file rather than by pasting the picture in. The interesting part is the iteration machinery: an arrow plan that forces every connector to cite a fact recorded from the original, and a gate that refuses to count a round which only edited metadata.

**Rss3208/Visiomaster** — A Visio diagram-reconstruction toolkit inspired by ppt-master, rebuilding flowcharts, architecture diagrams and paper figures from images into editable .vsdx files, with SVG/PNG export.

- Repository: https://github.com/Rss3208/Visiomaster
- Stars: 826 · Forks: 42
- Language: Python
- License: MIT
- Published: 2026-09-19 · Updated: 2026-09-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/rss3208-visiomaster

## The clone command in the skill install still has a placeholder owner

The instructions for installing as a Codex skill are four lines, and the first one has never been filled in.

```powershell
git clone https://github.com/<owner>/visiomaster.git "$env:USERPROFILE\.codex\skills\visiomaster"
cd "$env:USERPROFILE\.codex\skills\visiomaster"
python -m pip install -r requirements.txt
```

The repository reference is literally `<owner>`, so pasting this line clones nothing. The target path is real and correct: the skills directory under the user profile, a folder named `visiomaster`. The rest of the block is the same environment setup as everywhere else in the project.

For anyone who keeps a working copy rather than cloning, there is a sync script instead:

```powershell
python .\sync_to_skill.py --skill-dir "$env:USERPROFILE\.codex\skills\visiomaster" --merge-skill-md
```

The `--merge-skill-md` flag is described as trying to preserve the local environment settings already present in the target skill, which is the detail that makes it usable: without it, syncing your working copy over the installed skill would overwrite the machine-specific configuration you set up earlier.

Once installed, the skill is triggered in Codex as `$visiomaster`, which starts the image to editable Visio rebuild flow. The project states plainly that the real hard requirement is not Codex: it is the render stage, which needs Windows, Python, pywin32 and a local desktop install of Microsoft Visio. Codex, Claude Code or any other local agent is interchangeable; Visio is not.

## The self check launches Visio before anything else runs

Installation is one dependency file, and it has two entries.

```
pywin32>=306
Pillow>=10.0.0
```

That is the whole runtime requirement, because the rendering capability comes from somewhere else entirely: the project drives the locally installed Microsoft Visio desktop application through COM. pywin32 is the bridge, and Pillow is there for image work. Nothing in this list parses a Visio file.

So the first thing to do is prove the bridge works, which is what the environment check does.

```powershell
python .\scripts\check_visio_env.py
```

It attempts to start Visio, create a minimal drawing, save it as a `.vsdx`, and export a `.png` and a `.svg`. That is a real end to end test of the only part that can fail for reasons unrelated to your Python environment. If that step fails, the project says to fix the local Visio COM or export environment first, before touching anything else.

The stated platform requirements are Windows, the Microsoft Visio desktop edition, Python 3.10 or newer, and the dependencies in `requirements.txt`. The environment itself is unopinionated: system Python, a virtual environment or conda all work, as long as that interpreter can import pywin32 and can reach the Visio COM application on the machine.

The COM dependency has a consequence worth being explicit about. Every render step starts an external application, so headless and server-side use is out, and a machine with Visio but no interactive session may behave differently from the one the script was written on.

## Every connector has to cite an arrow fact recorded from the original image

The Arrow Plan Gate is the mechanism that makes faithful replication checkable rather than aspirational.

Before writing the first version of `scene.json`, you generate `metadata.arrow_plan` from the original image. Each arrow is recorded individually: its connection, its endpoints, whether it is straight, a polyline or a curve, whether it is dashed or solid, its arrowhead, and its semantic intent.

Then every visible edge in the scene binds to the matching arrow fact with an `arrow_plan_id`. And `scene_validate.py --strict` checks the bindings and the geometry together.

```powershell
python .\scripts\scene_validate.py .\work\figure_01\scene.json --strict
```

The specific failures it looks for are named. A missing binding, meaning an edge that claims no source fact. A horizontal arrow that has become a diagonal. A feedback path built from the wrong components. A boundary arrow that is not routed through a `boundary_port`. And a merge or fork that does not go through a junction or a bus.

Those five checks exist because each one is a specific way a reconstruction goes wrong that a whole-picture comparison would hide. An arrow is small, and it is exactly the kind of element that looks fine in a thumbnail and is wrong in the drawing.

The gate is part of a wider sequence rather than a standalone script. `stage_source_image.py` stages the source and records a hash of it, `scene_complexity.py` reports complexity, `scene_audit.py` generates a module level report and can be run with a flag that fails when a rebuild is needed, and `scene_to_visio.py` does the render. The source hash matters because the review loop compares against a fixed original; if the original changed, the comparison is no longer against what you thought it was.

## A round that only edits metadata is refused on purpose

The version's stated focus is not new components but the problem of iterating after a failed reconstruction, and the scripts it added are all about refusing to accept a bad round.

There is a no-op gate, `round_noop_gate.py`, whose purpose is stated plainly: it stops a round that only changed metadata, or that rendered without effect, from counting as progress. That is a guard against the easiest way for an automated improvement loop to lie to itself, since a metadata edit is always cheap to make and always looks like a change.

Then the review chain. `make_review_assets.py` builds the review bundle, which is the pair of images plus the manifests the later gates read. A vision capable LLM looks at the original and the current replica, and the result is written to `review_findings.json`.

```powershell
python .\scripts\review_checklist_gate.py .\work\figure_01\review_round_01\figure_01_review_findings.json --manifest .\work\figure_01\review_round_01\figure_01_review_manifest.json --require-failed-refs
```

That gate runs with a flag requiring failed references, which is what stops a review that quietly marked everything as passing. The findings are then converted into a rebuild brief, again with a requirement flag:

```powershell
python .\scripts\review_findings_to_repair_plan.py .\work\figure_01\review_round_01\figure_01_review_findings.json --scene .\work\figure_01\scene.json --manifest .\work\figure_01\review_round_01\figure_01_review_manifest.json --require-checklists --output .\work\figure_01\review_round_01\figure_01_scene_rebuild_brief.json
```

And a regeneration packet is prepared from that for the next attempt.

The principle the project states about all of this is the part to hold on to: the visual review must look at two images, the original and the current replica PNG, and the Python scripts are only auxiliary gates. They cannot stand in for a human or a vision model judging whether the reconstruction is right.

## rounded_orthogonal_connector exists because a smooth curve bends the straight parts

One rendering addition deserves its own note, because the reason for it is a rendering artefact rather than a style preference.

The new connector type is called `rounded_orthogonal_connector`, and it produces an orthogonal line with smooth corners. The stated reason it was added is that using a global smooth curve to get the rounded corners bends the straight segments as well. So the connector keeps the horizontal and vertical runs exactly where they were and rounds only the corner.

In a flow diagram that difference is the difference between a diagram that reads as designed and one that reads as a curve drawn through a grid.

The companion reference is `references/renderer-effective-fields.json`, and its existence says something important about the design philosophy. The project publishes a machine readable list of which scene fields actually affect the rendering. That is an admission that a scene description can contain fields the renderer ignores, and rather than hiding that, the project documents it so a reconstruction can be checked against what will actually be drawn.

The scene model itself is described as the intermediate protocol between image analysis and Visio rendering, covering page size, nodes, edges, styles, resources and replication metadata. Alongside `scene.json` describing nodes, containers, connections, fonts, formulas, local regions and review metadata, the reference directory holds the schema, a component map of supported components and rendering intent, and the Visio COM export flow with its troubleshooting notes.

The pipeline as a whole is a loop rather than a line: source image, staging and visual inventory, `scene.json`, then validation, complexity and audit, then the Visio COM render producing the vsdx, svg and png, then a visual model review, then a rebuild brief and regeneration packet, then a full scene rebuild.

## Three update documents dated May are cited by a release dated September

The release history and the update notes do not line up.

The three most recent releases are v0.3.0 on 2026-05-27, v0.3.1 on 2026-05-28, and v0.3.2 on 2026-09-14, whose title names deterministic quality gates and authoring accelerators. The last push to the default branch is recorded as 2026-09-14 and the repository is not archived.

The update documents the page points to for the current version's changes are dated 2026-05-27, 2026-05-28 and 2026-05-29.

The three file names under the updates directory are a release preparation note, an arrow plan gate note, and a rounded orthogonal connector note. The first two dates coincide exactly with the v0.3.0 and v0.3.1 release dates, and the third, 2026-05-29, has no release date of its own at all.

So the section describing this version's focus is describing work documented in late May, while the version carrying it was published in September. Whatever happened in between, the practical consequence for a reader is that the changelog entry is not a reliable index of when each feature appeared, and the per date notes are the better record.

The repository also ships a separate `RELEASE_NOTES.md` at the root, alongside `SKILL.md` and an `agents/` directory, which is where a second version of this history may live.

## Two Python packages, two ways in, and a paid service for people who would rather not set up Windows

The dependency list being two packages long has already been covered, and it is a consequence of the design rather than a thin one. What is left is how the toolkit is entered.

There are two routes. Used directly as a command line tool, you write or generate a `scene.json` by hand and then run the scripts under `scripts/` to validate, audit and render it. Used as a skill or context for an AI coding assistant, Codex, Claude Code or another local agent reads `SKILL.md`, references the scene specification, and calls the same scripts. The second route is a packaging decision, not a different engine.

The entry point from an image is deliberately limited. `image_to_scene.py` takes an image, a template name and an output path, and it is described in the strongest terms available: a starting scene generator, not a fully automatic precise replication engine. For complex diagrams, structure decomposition, local checking and the rebuild still need a vision model or a person.

```powershell
python .\scripts\image_to_scene.py --image C:\path\source.png --template basic-flow --output .\work\scene.json
```

There is also a component strategy decision worth knowing. The toolkit uses a controlled semantic component vocabulary rather than exposing every Visio stencil, and the stated reason is to reduce the variation that comes from different Office languages, versions and template names. That sentence is where the project page ends, so the full reasoning and the component list have to be read out of `references/visio-component-map.md` and `templates/visio_components.json`, alongside `templates/style_profiles.json` for visual style.

Finally, the project page offers a paid online service for anyone who wants to try the reconstruction without configuring Windows, Visio, Python and an agent environment. Uploading a reference image there gets a rebuilt Visio drawing with the same file outputs. It is a commercial fallback for the environment requirement, and it is stated as such on the same page as the open source repository.

## Conclusion

Use Visiomaster if you need a deliverable someone else can edit in Visio rather than a picture of a diagram, and if you have a Windows machine with desktop Visio, because that is not negotiable: the renderer drives the application through COM and the dependency list is two packages. Read the strict replication flow before starting, since the arrow plan and the two-image review are where the quality actually comes from, and an export you judge from the overall PNG alone is exactly what the project tells you not to do. Two things to fix on your own copy. The Codex install line still carries a placeholder repository owner, so clone it yourself rather than pasting it. And the scene component vocabulary section ends mid-sentence in the project page, so the mapping from your shapes to supported components has to be read out of the component map reference instead.

## FAQ

### What does Visiomaster need in order to run?

Windows, the Microsoft Visio desktop edition, Python 3.10 or newer, and the two dependencies in `requirements.txt`, which are pywin32 and Pillow. The rendering goes through the locally installed Visio application via COM, and `python .\scripts\check_visio_env.py` verifies that by starting Visio, saving a minimal `.vsdx` and exporting a PNG and an SVG.

### Is image_to_scene.py a fully automatic replication tool?

No. The project describes it as a starting scene generator rather than a fully automatic precise replication engine. For complex diagrams, structure decomposition, local checking and the rebuild still require a vision capable LLM or a person.

### What is the Arrow Plan Gate in Visiomaster?

Before writing a scene you record `metadata.arrow_plan` from the original image, with each arrow's connection, endpoints, shape, dashed or solid style, arrowhead and intent. Every visible edge then binds to a fact with an `arrow_plan_id`, and `scene_validate.py --strict` checks for missing bindings, horizontal arrows turned diagonal, wrong feedback path components, boundary arrows not using `boundary_port`, and merges or forks not using a junction or bus.

### How does Visiomaster decide whether a reconstruction round counted?

A no-op gate refuses rounds that only changed metadata or rendered without effect. The review chain then builds assets, has a vision model compare the original and the replica, converts the findings into a rebuild brief, and prepares a regeneration packet, with gates that require failed references and checklists rather than accepting an all clear.

### How do I install Visiomaster as a Codex skill?

Clone or copy the repository into the Codex skills directory under your user profile and run `python -m pip install -r requirements.txt`, then invoke it as `$visiomaster`. Note that the clone command printed in the project page still contains a placeholder repository owner, so supply the real URL yourself. A `sync_to_skill.py` script handles working copies, and its `--merge-skill-md` flag preserves local settings in the target.

### Which files describe the scene.json format and the supported components?

`references/scene-schema.md` covers the fields, coordinate rules and fidelity metadata, `references/visio-component-map.md` covers supported components and rendering intent, `references/visio-export-flow.md` covers the Visio COM export flow and troubleshooting, and `references/renderer-effective-fields.json` records which scene fields genuinely affect rendering.

## Sources

- [Issues](https://github.com/Rss3208/Visiomaster/issues)
- [License: MIT](https://github.com/Rss3208/Visiomaster/blob/main/LICENSE)
- [README](https://github.com/Rss3208/Visiomaster/blob/main/README.md)
- [Releases](https://github.com/Rss3208/Visiomaster/releases)
- [Rss3208/Visiomaster on GitHub](https://github.com/Rss3208/Visiomaster)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rss3208-visiomaster