Importing and converting (text, files, photos, data)

The Studio can start from almost anything you already have: a sentence describing the diagram, code copied from a web page or a paper, a file on your computer, a Mermaid Live or PlantUML link, a photo of a whiteboard, a sketch, a SQL schema, a spreadsheet of numbers — and once a figure exists, it can be converted to another engine. This page covers every way in, from the Studio's launchpad to drag and drop, the Import a diagram dialog, Photo → Engine, the schema importer and Convert to another engine…, with the exact formats, limits, plans and messages for each.

At a glance

AI on flowss: the Free plan has no AI; Starter can use your own AI key; Plus and above include hosted AI points. Everything marked "No" above works on every plan. See AI in flowss and AI points and limits.

The Studio launchpad

Opening /studio with nothing else in the address shows the launchpad, headed How would you like to begin? (the last word changes: begin, create, map it out, visualise it, break it down). Beside the headline an animated preview shows the ways in; Pause the preview stops it, and the headline with it. The launchpad respects your system's reduce-motion setting.

To see the launchpad again after skipping it, use ⋮ → New from the launchpad… in the editor (or ⌘K). Whatever a launchpad door produces opens in the editor as a new figure — named "Shared Mermaid diagram" (with its engine's name) for the Describe, Paste and data doors, or simply after the engine for Pick an engine. Double-click the title to rename it.

Describe it: Type / speak

1. Type what you want into the box. While it is empty and idle, the placeholder types examples ("Try: a sequence diagram for OAuth 2.0 login…").
2. Or select the microphone, Dictate via voice, and speak; select it again (Stop recording) to finish. What you say is added after anything already typed. Dictation uses your browser's speech recognition in your browser's language.
3. Or select one of the Try examples, such as "PRISMA 2020 flow: 1,284 records identified, 870 excluded, 45 included" or "Kanban board for a sprint with To do, In progress, Review, Done".
4. Select Build diagram or press ⌘↵. The status reads "Picking an engine and drafting…" and the source streams in underneath as it is written.

The AI picks the engine and writes the source, and the editor opens on the result.

Describe it: Upload photo

Drop an image on the box ("Drop a photo here or click to upload") or select it to choose a file. Whiteboards, textbook figures, circuits, floor plans and sheet music all work. The box says PNG / JPG · up to ~3 MB: any image file is accepted, but a photo larger than about 3 MB is refused by the reader. The status reads "Reading the photo…". Anything you have typed in the Type / speak box is sent along as a hint.

Describe it: Draw a sketch

Draw boxes, arrows and labels on the white pad with a mouse, pen or finger. Undo removes the last stroke and Clear empties the pad. Select Convert sketch; the status reads "Reading your sketch…", and the AI reads the drawing as a diagram and picks the best engine.

Describe it: Start with data

This door turns rows of numbers into a chart without AI: every value is embedded exactly as you gave it and checked before the editor opens.

1. Paste CSV, TSV or JSON rows into the box, drop a file on it, or select Upload CSV / TSV / JSON (files up to 500 KB; .csv, .tsv, .txt and .json).
2. A summary appears, such as "120 rows · 4 columns — 3 numeric, 1 dates". Any notes about the parse (for example short rows read as blanks) appear in amber; the rows are still usable.
3. Choose what to do:

Larger datasets (up to 200,000 rows) belong in the Figure studio, which reads whole files.

Paste code

1. Paste diagram source into the box (the placeholder shows a small PlantUML example). Mermaid, PlantUML, DOT, DBML, Vega-Lite and many more are recognised.
2. Select Detect & open or press ⌘↵. A chip names what was found, such as Mermaid · certain, and the editor opens a moment later.

Recognisable source and links are identified instantly on your device, with no AI. Only when the text cannot be identified locally is it sent to the AI detector, which counts as one AI request. If even that fails: "Couldn't identify the engine — pick one manually below." You can also paste a link here; the link types are listed under Opening a link.

Pick an engine

The grid lists every engine on the Studio canvas in the same domain groups as the editor's Library (Flow & UML, Flow systems, Risk & reliability, Quality & control, Architecture, Charts & data, Schemas & layouts, Research & analysis, Engineering & physical, Domain-specific, More), with a badge counting them. Each button shows the engine's name and language; hover for its description. Search engines… filters by name, id, description or the tool it is compatible with; with nothing found, Clear the search and see all brings the full grid back. Select an engine to open a new figure on its starter template. No AI is involved.

BPMN and Weave are not in this grid because they have studios of their own: BPMN and Weave.

Importing inside the editor

Once you are in the editor, these are the ways in:

Imports never overwrite your work: a file, link or paste that becomes a figure always becomes a new figure, except where noted below (the schema importer fills an empty figure in place, and Photo → Engine and Use in Studio put the result into the open figure, where ⌘Z undoes it).

Pasting anywhere

Copy a diagram from anywhere and press ⌘V in the Studio — anywhere except inside the code editor or a text box, where ⌘V pastes normally.

• A copied image (a screenshot, a picture copied from a web page) opens Import a diagram on its Photo / camera tab with the image loaded, and recognition starts straight away. This uses AI.
• Copied text that looks like a diagram opens the dialog on Paste code or URL and detects it. "Looks like a diagram" means: a recognised engine keyword, a link to a known diagram tool, a JSON diagram or chart spec, SVG or BPMN/draw.io XML, at least two lines with arrows such as -> or -->, or DBML table and ref lines.
• Anything else (an ordinary sentence, a colour code, a link to an unrelated page) pastes as normal text and the dialog does not open. Very short pastes of under six characters are ignored.

Dropping files

Drag a file over the Studio and an overlay appears: Drop to import, with a reminder of what goes where. What happens depends on the file:

The new figure is titled after the file name. Dropped files are limited to 2 MB; larger files are refused before they are read ("… is … MB — too large to import here (the limit is 2.0 MB). Large datasets belong in the Figure studio (up to 200,000 rows); diagram source this big will not render."). Only the first file of a multi-file drop is used.

Opening a file

⋮ → Open a file… (or ⌘K) opens your computer's file picker. It accepts .mmd, .mermaid, .puml, .plantuml, .iuml, .wsd, .dot, .gv, .d2, .dbml, .svg, .nwk, .newick, .bpmn, .xyz, .pdb, .md, .excalidraw, .drawio, .sql, .json, .txt and .xml, up to 4 MB. The extension decides the engine where it can; otherwise the content does:

• A known engine's first keyword (@startuml, graph TD, flowchart LR, sequenceDiagram, digraph, a BPMN definitions root…) decides it.
• JSON is read by what it declares: an Excalidraw scene, a Vega or Vega-Lite $schema, a Plotly trace list, a Weave board, a Cytoscape node-and-edge list or a WaveDrom signal list.
• A .sql, .dbml or .drawio file goes to the schema importer. A .xml file goes there too, unless its content is recognised as an engine's document (for example a BPMN process saved as .xml), in which case it opens as that engine.

A successful open says "Opened as Mermaid" (with the engine's name). A refusal says why and what would work, for example "Couldn't tell what that is. Diagram source opens straight away when it starts with its engine's keyword (graph, digraph, @startuml…); otherwise pick the engine first and paste into the editor."

Opening a link

⋮ → Open a link… (or ⌘K) opens Import a diagram on its paste box. Paste a link and select Import from URL:

No other website is ever fetched on your behalf. Any other link is refused with: "Nothing here can open that link. Mermaid Live, PlantUML server, Kroki and GitHub/Gist raw links open directly; for anything else, paste the diagram source itself." Fetching a raw file gives up after 15 seconds, and files over 4 MB are refused.

The Import a diagram dialog

Import a diagram is one dialog for photos, pasted code and links. It opens from ⋮ → Import ▸ Photo, camera or clipboard…, the empty canvas's Import button, ⌘V and Open a link…. It has two tabs.

Photo / camera

Uploaded images are scaled down to at most 1,600 pixels on their longest side before they are sent. Recognising a photo costs twice a standard AI request (2 AI points on a hosted plan). The Upload a file picker accepts PNG, JPEG, WebP, GIF and SVG images as well as diagram files. Closing the dialog (× or Escape) always turns the camera off.

Paste code or URL

Paste diagram code or a link into the box, or select Paste from clipboard to read your clipboard directly. Select Detect & import (or Import from URL for a link).

• Links are handled exactly as in Opening a link.
• A draw.io / diagrams.net export is converted on your device into a Weave board: "Imported 24 shapes from draw.io", with each page laid out side by side.
• Other text gets an instant local guess at its engine, which the AI detector then refines when AI is available. If detection is unavailable (offline, no AI, the daily limit reached), the local guess — or Mermaid — is used anyway, and the note says "Imported as Mermaid. If that's not right, switch the engine after importing."

The result

When something has been read, the dialog shows the engine's name, an engine guess percentage when the AI supplied one (this is how sure it is of the engine, not a measure of how faithfully your drawing was read), any notes, and the first part of the source. Then:

A draw.io import becomes a Weave board. On the Studio canvas a Weave board shows Weave has its own studio with Open Weave →, which carries the board into Weave (Starter and above).

Photo → Engine

Photo → Engine is the advanced photo reader, for when a quick recognition is not careful enough. It is part of Plus, Ultra and Enterprise. Open it from ⋮ → Import ▸ Photo → Engine (convert a photo to a diagram) or ⌘K. On other plans it opens a short explanation with See plans and Not now.

1. Drop a photo, paste a screenshot (⌘V), select Choose file, or Take photo (opens the camera on a phone). Photos are scaled to at most 2,048 pixels before sending.
2. Choose a Fidelity:

1. Choose an Engine: Auto-detect (recommended), or force one of about a hundred, such as "Flowchart / sequence diagram (Mermaid)", "UML / PlantUML", "Circuit schematic", "Entity-Relationship diagram", "Project schedule (Gantt with critical path)" or "Markmap (mind map)".
2. Optionally add a hint ("Optional hint — e.g. "it's our deploy pipeline"").
3. Select Analyse photo. The result shows the engine, how confident the reader is ("87% confident"), notes, and a live preview of the diagram before anything touches your editor.
4. If the engine looks wrong, select one of the Also try: chips to re-read the same photo into a different engine.
5. If the preview looks wrong, select Preview looks wrong? Ask the flowss Studio Agent to fix it, describe the problem ("the two right-hand boxes are missing") and select Fix it. Re-analyse runs the whole reading again; Different photo starts over.
6. Select Insert into Studio. As the footer warns, "Inserting replaces the editor's current source." — the open figure gets the new source (⌘Z undoes it), and a toast confirms "Loaded the recognised … source into the editor". If the chosen engine lives in another studio, the button reads Open in its workstation and takes you there.

The schema importer

⋮ → Import ▸ Import SQL / DBML / draw.io (paste or file) opens Import SQL / DBML / draw.io. It also opens by itself when you drop or open a .sql, .dbml, .drawio or .xml file, with the file already loaded.

1. Paste a schema into the box, drop a file on the box, or select Upload .sql / .dbml / .drawio. "pg_dump, mysqldump and hand-written DDL all read".
2. The dialog says what it recognised:

1. If the SQL conversion skipped or simplified anything, the dialog stops and lists it — "Converted with 3 warnings — nothing was skipped silently:" (the first eight, then "…and N more"). Select Import anyway to continue, or Cancel.

Where the result goes: an empty open figure is filled in place; otherwise the schema becomes a new DBML figure titled after the file (or "Imported schema"). The toast reads "SQL converted to DBML", "DBML imported" or "Imported with N warnings". The conversion runs on your device with no AI. Afterwards Diagnostics checks the schema (missing primary keys, broken refs, type mismatches); see The Studio editor.

AI import: code, data or text into diagrams

⋮ → Import ▸ flowss Studio Agent: import code / data → diagram opens the flowss Studio Agent in its import mode, whose box reads "Paste code, SQL, JSON or an outline to turn into diagrams…". Paste source code, a schema, data or an outline and the flowss Studio Agent decides which diagrams describe it and builds them. You can instead paste a public file URL (GitHub, Gist, GitLab) into "…or paste a public file URL" and select Import. A related mode updates an existing diagram from a changed source. This needs AI on your plan. See The flowss Studio Agent and its modes.

Converting to another engine

⋮ → Convert to another engine… (or ⌘K) opens Convert to another engine. It carries the open figure's diagram into a different engine — unlike picking an engine in the Library, which replaces it with a starter.

Instant converters

When a built-in converter exists for your engine and can read your source, it is listed first under Instant · Mermaid → (with your engine's name). These run on your device, cost nothing and need no AI:

Every instant conversion is checked. If it carried everything, the result is applied silently; if only styling was lost, it is applied and a toast names what did not carry; if structure (a node, connection, label or group) would be lost, nothing is applied and the error names what would be lost, with Convert with the flowss Studio Agent instead.

Convert with the flowss Studio Agent

Under Convert with the flowss Studio Agent to… every other engine is listed, with Search engines… to find one. Select one and the status reads "Converting your diagram…". The conversion still prefers a built-in converter where one exists and uses AI otherwise. If AI is unavailable to you and a built-in converter can do part of the job, its result is applied with a warning naming what did not carry. A figure with no source simply switches to the new engine's starter.

The converted diagram replaces the open figure's engine and source as one undo step. If you switch figures while an AI conversion runs, the answer still lands on the figure it was for, with an Undo in its toast.

To hand a diagram to another studio (BPMN, Figure, the Lab and the rest) rather than another engine, use Send to another studio…; see Moving work between studios.

Tips

• For known formats, paste beats describe: pasting source is instant, exact and free, while describing costs an AI request and is an interpretation.
• Give photo readers a hint ("this is our CI pipeline", "UML class diagram"); it noticeably steers the engine choice.
• Use Faithful in Photo → Engine for evidence you must not change (a whiteboard from a meeting), and Clean up for a diagram you will publish.
• For a SQL dump, import it as DBML first and then use the instant Mermaid ER converter if you need Mermaid.
• Mermaid Live, PlantUML and Kroki links are decoded on your device, so they import even when the original site is unreachable.
• Dropping a .json file assumes a Plotly or Vega-Lite spec. For a Vega, Excalidraw, Cytoscape, WaveDrom or Weave JSON file, use Open a file…, which reads what the JSON declares.
• Before Use in Studio, Insert into Studio or a conversion on a figure you care about, consider making a new figure (⌥⌘N) — though ⌘Z always undoes them.

Limits and known constraints

• Describe, photo and sketch reading, AI engine detection for text that is not recognised locally, AI import and AI conversion all need AI: Starter with your own key, or Plus and above. Free has no AI.
• Photo → Engine is limited to Plus, Ultra and Enterprise; bringing your own key does not unlock it on other plans.
• Dropped files: 2 MB. Opened files, pasted text and fetched links: 4 MB. Launchpad data files: 500 KB. Photos: about 3 MB after scaling.
• Only raw GitHub and Gist files are fetched from the web; other sites must be pasted as source.
• Mermaid Live links compressed with #pako: need a browser that can decompress them; very old browsers are told to paste the source instead.
• Instant converters cover only the pairs listed; Mermaid's instant converters read flowcharts only (other Mermaid types go through AI).
• draw.io diagrams become Weave boards and open in Weave, which needs Starter.
• On a Free account whose Studio already holds 3 figures, opened and dropped files and schema imports that need a new figure are refused with the limit message. Launchpad results arrive as an unsaved view you can read and edit, and keep with Keep this shared diagram once you make room. Use in Studio, Insert into Studio and conversions are never refused, because they replace the open figure instead of adding one.

Troubleshooting

Related pages

• The Studio editor
• Starting from a template
• Choosing an engine
• Data, timeline, TikZ and the diagram tools
• The flowss Studio Agent and its modes
• Moving work between studios
• Figure
• Weave
• AI in flowss
• AI points and limits
• Bring your own AI key
• Engine reference