Protocol Drawing Studio

Draw scientific diagrams with code, then edit their vectors in your browser. The browser editor uses SVGEdit; the embedded assistant uses the original shared ai-ify package. Python serves the complete editor locally. Node.js is not required to open, edit, insert library images, save, or publish an agent revision.

Install and open

python -m pip install protocol-drawing-studio
protocol-drawing drawing.svg

Run protocol-drawing without a filename to start a blank drawing. The command reuses one local server and opens the user's default browser. Use protocol-drawing-server --port 3017 for a foreground server.

Requires Python 3.11 or later. Windows is the verified desktop platform; Linux and macOS use portable paths and launch logic but are not yet desktop-tested. The package provides a Windows command launcher; a standalone desktop installer and Explorer file association are separate distribution work.

Manual editing

Select objects on the canvas or in the Objects tree. Delete/Backspace removes selected objects; arrows move them and Shift makes larger movements. Native undo and redo cover edits, inserted components, layout and attached arrows. Ungroup splits artwork into editable parts. The Components view can insert an image into the current editor, or open it as a separate drawing.

Save working copy creates a new SVG under the user's application-data directory; it never overwrites an opened original. Unsaved recovery, named styles and favourite images are stored in that browser. Interface preferences follow the browser origin rather than an account.

Generate drawings in Python

from pathlib import Path
from protocol_drawing.library import components, compose

matches = components('pipette')
svg = compose([{'component': matches[0]['id'], 'x': 100, 'y': 100, 'width': 200}])
Path('drawing.svg').write_text(svg, encoding='utf-8')

components(query) returns catalogue metadata including exact IDs and licences. compose gives each instance independent vector IDs and retains attribution inside a non-visible description. Agents can create arbitrary SVG paths, text and groups; using a library image is optional. Keep text editable and concise. SVG exports must be self-contained vectors, not scripts, embedded raster images or external resources. Do not remove attribution when editing borrowed artwork.

Register newly made artwork for local reuse:

from protocol_drawing.library import register_component
register_component('my-vector.svg', id='user.pipette', title='My pipette', tags=['pipette'])

Local components appear in the editor's library and in components(query). They live exclusively in user data. To revise a frozen component, register a new ID. Supply the attribution argument with the original creator/source/licence when registering borrowed artwork; registering does not change its licence.

Assistant and marked feedback

The assistant panel, provider selection, conversation and browser command bridge come from the separately maintained ai-ify dependency. AI use additionally requires a configured supported provider/agent command and its own authentication; installing the editor does not supply an AI account. Manual editing works without one. See ai-ify for provider setup.

Draw feedback marks over the picture, add a concise request, then send it through the shared panel. Background mode works from the exact manually edited snapshot. An agent writes a candidate into the supplied candidate directory and calls drawing.publish. The preview applies it only if the working revision still matches; concurrent user edits are preserved. Marks remain outside the saved SVG. Live commands also require the current revision.

The assistant can discover images using protocol_drawing.library.components or the editor's /api/components endpoint, and compose vectors with the Python API. For optional React/Remotion authoring, set PROTOCOL_DRAWING_REMOTION to a separate compatible project containing tools/draw.tsx, with Node.js and its dependencies installed. Such a project is not part of this distribution.

Library and licences

The public catalogue contains selected downloaded BioIcons and Health Icons artwork. Every included record has an allowed individual licence, source URL, creator, original source hash and recorded modifications. Full licence texts and per-image attribution ship with the package. The Components view displays the credits; inserted SVG groups retain them as non-visible descriptions.

This distribution contains no private experiment figures, custom reusable components, agreed templates, output folders or local scene projects. Images larger than the editor's 5 MiB limit, unsupported vectors, and records outside the release licence policy are excluded by the preparation script. See THIRD_PARTY_NOTICES.md.

Original editor code: MIT, Copyright 2026 Brancaccio Lab. Third-party images and vendor code retain their own licences; MIT does not replace those terms.

Storage and troubleshooting

State and working files use the user's application-data directory, never the installed package. Set PROTOCOL_DRAWING_STATE to override it. Server logs are written there. Close the originating editor before using its Components tab; an orphaned library tab cannot insert into a closed editor.

The server listens only on this computer. If startup fails, inspect desktop-server.log in the state directory. A unavailable AI provider does not require reinstalling the editor; configure it through ai-ify.

Release development

The browser files are prepared from the maintained editor, not a second fork. Run the parent project's tools/prepare_public_package.py to synchronise the explicit source allowlist and licensed catalogue. Build wheels and source archives with python -m build; check metadata with python -m twine check dist/*. Test a wheel in an isolated environment outside the source checkout.