Bantam Tools

Bantam Tools Studio™

User Guide

Prepare, preview, and send your artwork to Bantam Tools drawing, writing, and painting machines.

Download PDF
Last updated November 17, 2026

Bantam Tools Studio™

User Guide

Prepare, preview, and send your artwork to Bantam Tools drawing, writing, and painting machines.

Last updated November 17, 2026

Part I: Getting Started

0. Preliminaries #

This chapter explains how the guide is organized, gives a short path from installation to a first job, and lists where to get help and updates. It is the starting point for readers new to Bantam Tools Studio™.

0.1 About this user guide #

This is the user guide for Bantam Tools Studio™ software. Bantam Tools Studio prepares artwork, text, and machine instructions for Bantam Tools machines, including ArtFrame™, EggBot™, WaterColorBot™, and Bantam Tools HandWriter®.

This guide explains the shared Studio workflow first: selecting a machine, preparing files, assigning tools, previewing motion, generating G-Code, uploading jobs, managing machine files, and tuning settings. Later chapters cover specialized workflows, including painting, converting images with the Image Processor, and the Bantam Tools Studio Text Add-On.

Bantam Tools Studio is a motion and process tool. It prepares reliable machine motion for real tools working with real materials.

0.2 Quick start #

If you are new to Bantam Tools Studio and want to get running quickly, start here:

  1. To download, install, and activate Bantam Tools Studio, check your inbox for the email sent at the time of purchase containing your download link and license code, then follow §2. Installing Studio.
  2. To understand the basic Studio workflow, see §3. Getting started.
  3. To select or configure your machine, see §4. Machine selection and setup.
  4. To prepare an SVG file for drawing or plotting, see §12. The PREPARE tab.
  5. To connect to your machine and send a job over microSD, USB, or WiFi, see §10. Sending files to your machine.
  6. To paint with Bantam Tools Studio, see §8. Painting.
  7. To turn a photograph into artwork to paint or plot, see §9. The Image Processor.
  8. To personalize a document with a Signature, see §13.4 Signatures. To unlock expanded writing features like the full font library and Handwriting Defects, see §6. Writing text; for Data Merge, see §7. Data Merge.
  9. To generate your first letter from copied text or a simple text file, see §6. Writing text.
  10. To generate personalized documents from a CSV file, from a first merge through conditional text and future rows, see §7. Data Merge.
  11. To design custom .svg templates in Inkscape for more controlled, professional layouts, see §20. Appendix: SVG templates in Inkscape.

0.3 Support resources #

If you need assistance or have questions, we’re happy to help. Please reach out through any of these channels:

0.4 Updates #

You can download the latest version of this guide at https://bantam.tools/btsguide. We encourage you to check back occasionally for the latest version.

Bantam Tools Studio automatically checks for updates on launch when an internet connection is available and provides a link to the latest download when one is available.

You can also check for updates from the SETTINGS tab inside Bantam Tools Studio.

1. About Studio #

Bantam Tools Studio prepares work for Bantam Tools machines. It can turn SVG artwork into machine motion (G-Code) for drawing, painting, and writing. Across all workflows, you set how a physical tool moves through space: where it goes, how fast it moves, when it contacts the surface, and how it interacts with the material.

The same basic idea applies whether the tool is a pen, brush, marker, or other supported implement: your settings direct the motion, and the mark on the surface comes from the real tool, the real material, and the real machine.

Artwork can be created upstream in many different tools, including vector design applications such as Adobe Illustrator and Inkscape, generative environments like Processing and p5.js, and plotter-focused tools such as vsketch. As long as the output is a valid SVG, Bantam Tools Studio can prepare it for machine motion.

Studio also draws text. With the included Hershey fonts, the text in an SVG document becomes single-stroke pen paths, with no upgrade required. For a more advanced letter-writing workflow with additional fonts, signatures, Handwriting Defects, spacing controls, and Data Merge, add the Bantam Tools Studio Text Add-On.

For painting workflows, you set up brush motion, refill behavior, palette interaction, and tool sequencing. Paint, water, paper, brush pressure, and pigment behavior remain physical. The software gives structure to the process, while the materials complete the work.

2. Installing Studio #

Bantam Tools Studio™ is the application you use to prepare a job and send it to your machine. This chapter covers finding your license details, downloading and installing Studio on macOS and Windows, and activating your license. You do this once, before your first job, and again whenever you move Studio to a new computer.

2.1 Finding your license details #

A license for Bantam Tools Studio is included with every Bantam Tools machine.

When you purchased your machine, or purchased Studio on its own, you received an email with a download link and a license key. Find that email before you begin: activation asks for the License ID and Password it contains.

If you cannot locate that email, contact support@bantamtools.com and include your order number or machine serial number, and we can send your license details again.

2.2 Downloading Studio #

Visit bantam.tools/sd to download Bantam Tools Studio. The download page offers a macOS disk image (a .dmg file) and a Windows installer (an .exe file); take the one for the computer you will be working on.

2.3 Installing on macOS #

  1. Locate the downloaded .dmg file and double-click it to mount the disk image.
  2. Review and accept the End User License Agreement.
  3. Drag BantamToolsStudio into the Applications folder.
  4. Eject the disk image.
  5. Open Bantam Tools Studio from the Applications folder.

The mounted disk image: drag BantamToolsStudio into the Applications folder.
The mounted disk image: drag BantamToolsStudio into the Applications folder.

Studio opens to the Select Your Machine splash screen. Choose your machine and Studio continues to its main window, with no license active yet. The splash screen has a Don't show this again check box; with it checked, later launches open straight to the machine you used last.

Select Your Machine window at startup
Select Your Machine window at startup

2.4 Installing on Windows #

  1. Locate the downloaded .exe installer and run it.
  2. Click Next to begin.
  3. Choose an installation folder.
  4. Review and accept the End User License Agreement.
  5. Accept Bantam Tools Studio as the Start Menu shortcut name.
  6. Click Install.
  7. Click Yes when Windows asks whether to allow the installer to make changes, so that it can finish.
  8. Click Finish.

The installer closes and Bantam Tools Studio appears in your Start Menu. The first time you open it, it shows the Select Your Machine splash screen before its main window.

To update Studio later, close it and run the newer installer, choosing the same folder. The installer asks whether to upgrade, and keeps your license and settings. When you click Yes to upgrade, Windows asks right away whether to allow the installer to make changes, before the Install step; click Yes there as well.

2.5 Activating your license #

Studio keeps license tools in the License Manager, which you reach from the SETTINGS tab. Activation is per computer, so you repeat these steps on each computer you install Studio on.

  1. Open Bantam Tools Studio, choosing a machine at the splash screen if it appears.
  2. Select the SETTINGS tab.
  3. Click License Manager.
  4. Select Activate License.
  5. Enter the License ID and Password from your license email. Installation Name is optional; Studio sends it to the licensing server along with the activation, as a name for this computer.

Studio confirms the activation, and the features your license includes become available. The license that comes with a Bantam Tools HandWriter® includes the Bantam Tools Studio Text Add-On, so on a HandWriter the full writing workflow is active as soon as the license is.

The Activate License form, with a License ID, Password, and Installation Name filled in
The Activate License form, with a License ID, Password, and Installation Name filled in

Note

Activation contacts the Bantam Tools licensing server, so a live internet connection is required. It is needed only for the initial activation; once the license is active, Studio runs without one.

From the License Manager you can also deactivate the current license, which frees it to be activated on another computer. Deactivate before you retire or hand on a computer, so that the license is available where you need it next.

License Manager with a license active
License Manager with a license active

2.6 What your license includes #

Studio includes the TEXT tab, for writing with the Hershey single-stroke fonts that come with it.

The Bantam Tools Studio Text Add-On adds the complete font library, signatures, Handwriting Defects, spacing and overflow controls, and Data Merge. It is a separate purchase for Bantam Tools Studio.

The chapters on writing text and on Data Merge cover what each of them does.

2.7 Help with installation #

If you run into difficulty installing or activating Bantam Tools Studio, email our support team at support@bantamtools.com and we can walk you through it. Include your order number or machine serial number when the trouble is with a license.

3. Getting started #

Before you prepare your first job, take a few minutes to get oriented. This chapter walks through the shared Bantam Tools Studio™ workflow, the five tabs across the top of the window, the menu bar, the machine selector, and the two ways to bring in your own artwork or text.

3.1 The Studio workflow #

Studio has one shared workflow that applies across machines and materials:

  1. Choose the machine you are using.
  2. Open artwork or create text.
  3. Set the paper or work area.
  4. Position and scale the job.
  5. Assign tools.
  6. Preview the motion.
  7. Generate, save, or upload the job.

You can use this workflow for drawing, painting, plotting, or writing. The details change depending on the selected machine and toolset, but the structure stays the same.

Bantam Tools Studio with a sample drawing open on the PREPARE tab
Bantam Tools Studio with a sample drawing open on the PREPARE tab

3.2 The five tabs #

Studio organizes its entire workflow into five tabs across the top of the window:

A small colored dot overlays the MACHINE tab whenever a machine is connected or connecting: blue means connected, tangerine means connecting, and gray means disconnected.

The MACHINE tab with the blue dot of a connected machine
The MACHINE tab with the blue dot of a connected machine

Once a file is loaded, the PREPARE tab splits into two sub-tabs, SETUP and OPTIONS. §12. The PREPARE tab covers both in detail.

Studio toolbar with the PREPARE tab active
Studio toolbar with the PREPARE tab active

Studio has a menu bar with four menus. On macOS it is the system menu bar at the top of the screen; on Windows it runs across the top of the Studio window, and Alt with a menu's underlined letter opens it (Alt+F for File). The keyboard shortcuts below work on both platforms, and most of the same commands are reachable from the tabs and on-screen controls.

  • File

    • Open File... (⌘O / Ctrl+O)
    • Open Recent — the files you opened most recently, with Clear Menu at the end of the submenu
    • Save G-Code File... (⌘↩ / Ctrl+Enter)
    • Generate G-Code and Upload
    • Open Project... (⇧⌘O / Ctrl+Shift+O)
    • Save Project (⌘S / Ctrl+S)
    • Save Project As... (⇧⌘S / Ctrl+Shift+S)
    • Exit (Alt+F4; Windows only) — closes Studio, asking first about unsaved work

    For the project items, see §11.4 Project files.

File menu on macOS
File menu on macOS

3.4 Choosing a machine #

Tell Studio which machine you're using in one of two places:

Your machine choice loads the correct defaults for work area, margins, available toolsets, and machine-specific G-Code behavior. Studio supports six machine types: three ArtFrame™ sizes, the EggBot™, the WaterColorBot™, and Bantam Tools HandWriter®. For setup notes on each machine, see §4. Machine selection and setup.

Select Your Machine window at startup
Select Your Machine window at startup

Machine selection drop-down menu on the PREPARE tab
Machine selection drop-down menu on the PREPARE tab

3.5 Opening artwork or text #

Use the OPEN FILE button (⌘O / Ctrl+O) near the upper left of the window to bring in a file.

The chevron beside OPEN FILE holds a few more actions:

There are two common ways to begin a job in Studio.

To use text without the Text Add-On, open an SVG file that already contains text elements, such as your name, a title, a date, a label, or a hash from a generative work, so that short text is drawn as part of a larger plotted piece. When text rendering is enabled, Studio converts those SVG text elements into one of two included single-stroke fonts: Hershey Sans 1-stroke or Hershey Script 1-stroke.

Bantam Tools HandWriter owners have the advanced writing features unlocked. On other machines that run Studio, those features are available through the Bantam Tools Studio Text Add-On. For the full writing workflow, see §6. Writing text.

OPEN FILE menu opened from its chevron
OPEN FILE menu opened from its chevron

3.6 Dropping and pasting files #

Besides OPEN FILE, you can bring content into Studio by dropping files onto the Studio window or by pasting from the clipboard.

3.6.1 Dragging and dropping files #

Drag files from Finder or File Explorer and drop them onto any part of the Studio window. Studio can detect and use these dropped files:

Drop several SVG files together to open them as a batch; see §12.1 Opening files and file actions. A dropped image opens in the Image Processor; see §9.2 Opening the Image Processor. Drop one image or one project file at a time.

With the Bantam Tools Studio Text Add-On, Studio can also detect and use these dropped files:

Text and RTF files open as text documents, and several dropped together open as a batch. A CSV file becomes the data file for a Data Merge on the TEXT tab; see §7. Data Merge.

Drop one kind of file at a time: SVG files, text files, or a single image.

You can also open SVG files and Studio project files from outside the Studio window. On Mac, drop them onto the Studio icon in the Dock, or open them from Finder with Open With. On Windows, open them from File Explorer with Open With.

3.6.2 Pasting from the clipboard #

Press ⇧⌘V on Mac or Ctrl+Shift+V on Windows to paste from the clipboard at any time, or use the chevron menu beside Open File:

Open File → Open from Clipboard

Studio can detect and use these kinds of clipboard content:

When vector data is available, Studio prioritizes it.

With the Bantam Tools Studio Text Add-On, Studio can also detect and use:

Pasting any of these opens the content as a text document. Studio writes the words as they arrived; to revise them, edit the source and paste again. See §6. Writing text for that workflow.

3.7 Samples and generators #

When no file is loaded, the PREPARE tab's SETUP view shows a Samples and Generators section so you have something to try before you bring in your own artwork. Depending on your selected machine, you'll see up to four buttons: Sample Image (ArtFrame and WaterColorBot only), Sample SVG, Sample Text, and Sample CSV. Each sample except Sample Image has a Save to disk item in its own chevron menu, so you can keep a local copy to open again later; Sample Image opens a sample photograph in the Image Processor (see §9. The Image Processor) and has no chevron menu.

Sample Text and Sample CSV are part of the Text Add-On.

Below the section, a Tip: line offers a short hint about working in Studio, chosen at random from a set that suits your selected machine.

If you close the section, reopen it anytime from the chevron menu beside Open File:

Open File → Show samples and generators

Samples and Generators section with an ArtFrame selected
Samples and Generators section with an ArtFrame selected

3.8 Preparing the job #

Once artwork or text is loaded, the PREPARE tab's SETUP and OPTIONS controls set the paper, the placement, the tools, and how the machine moves. To see them used on one drawing, see §5. From drawing to G-Code; every control is described in §12. The PREPARE tab.

3.9 Sending the job #

When the job is ready, you can send it to the machine in one of three ways:

See §10. Sending files to your machine for the full sending workflow.

4. Machine selection and setup #

This chapter covers choosing the machine Studio prepares jobs for, what each of the six Bantam Tools machines needs, and what changes when you switch machines. It applies before a first job and whenever a different machine is set up.

4.1 Selecting your machine #

Bantam Tools Studio™ works with several different machines, and it needs to know which one you're using before it can set up a job correctly. Your machine choice sets the physical work area, the default paper or media size, the available toolsets, and the machine-specific G-Code Studio generates when you're ready to plot, write, or paint.

You choose a machine in one of two places:

The splash screen has a Don't show this again check box. Check it before you choose a machine, and Studio skips the splash screen at later launches and starts with the machine you last used. To see the splash screen again, use Reset All Settings on the SETTINGS tab; see §17. The SETTINGS tab.

Select Your Machine window at startup
Select Your Machine window at startup

Studio prepares one job for one selected machine at a time. Every PREPARE tab setting — paper size, margins, toolset, tool assignments, and G-Code options — applies to whichever machine is currently selected. If you own more than one Bantam Tools machine, switch to the right one from the Machine selection drop-down menu before you set up a job for it.

4.2 The six Bantam Tools machines #

Studio supports six machine types: three Bantam Tools ArtFrame™ sizes, the Bantam Tools EggBot™, the Bantam Tools WaterColorBot™, and Bantam Tools HandWriter®. The notes below cover what's different about setting up a job for each one.

All three ArtFrame sizes have a flat work area, in the sizes listed below, and support both drawing and painting workflows on paper, canvas, and other compatible surfaces. Selecting any ArtFrame size adds a Show Plotter option to the Preview toolbar's Rendering options menu, and enables the palette-based tools it shares with WaterColorBot (see below) in TOOLSET SETTINGS.

Show Plotter in the Preview rendering options menu, with ArtFrame selected
Show Plotter in the Preview rendering options menu, with ArtFrame selected

4.2.1 ArtFrame 1824 #

The most compact ArtFrame, with an 18" × 24" plotting area. A good fit for standard art paper, smaller canvases, and desks with less room to spare.

4.2.2 ArtFrame 2436 #

A mid-size ArtFrame with a 24" × 36" plotting area, for larger sheets, posters, and bigger canvases.

4.2.3 ArtFrame Panorama #

The largest ArtFrame, with a 24" × 72" plotting area. Its long, wide format suits panoramic artwork, banners, and multi-panel pieces.

the three ArtFrame sizes — 1824, 2436, and Panorama — shown to scale side by side
the three ArtFrame sizes — 1824, 2436, and Panorama — shown to scale side by side

4.2.4 EggBot #

The EggBot maps flat SVG artwork onto round or ovoid objects, such as eggs and ornaments, using a rotating cradle instead of a flat table. Because of that, the PAPER SETTINGS section is titled MEDIA SETTINGS for EggBot, and canvas size is measured in degrees instead of millimeters or inches.

The Standard Sizes drop-down menu in MEDIA SETTINGS offers three canvas sizes to start from: 360 × 90° (Egg) for standard eggs, 360 × 120° (Sphere) for round ornaments and balls, and 360 × 140° (Maximum) for the largest object EggBot supports. Choose the size closest to your object's shape, then fine-tune the canvas size to match its actual dimensions.

The EggBot MEDIA SETTINGS section, sized in degrees
The EggBot MEDIA SETTINGS section, sized in degrees

The Preview toolbar's Rendering options menu adds 3D Egg Preview, Sphere Shape, and Egg Shape options for EggBot, so you can check how flat artwork will wrap around the object before you plot. For irregular or not-perfectly-round objects, you may need to adjust your tool's height settings in the Tool Library to give it more clearance; see §14. The Tool Library.

Tip

Parallel lines in your 2D artwork may appear closer together once wrapped onto a round object, the same way longitude lines meet at the poles of a globe.

PREPARE tab with EggBot selected and the 3D PREVIEW below the flat preview
PREPARE tab with EggBot selected and the 3D PREVIEW below the flat preview

4.2.5 WaterColorBot #

The WaterColorBot uses brush-based painting instead of pen plotting. Selecting it enables the same palette-based tools in TOOLSET SETTINGS as ArtFrame, and the Tool Library adds paint-specific tool settings such as Refill Mode and Prime/Wash; see §14. The Tool Library. For the full painting workflow, see §8. Painting.

TOOLSET SETTINGS on WaterColorBot, with a painting toolset and palette
TOOLSET SETTINGS on WaterColorBot, with a painting toolset and palette

4.2.6 HandWriter #

HandWriter writes on US Letter, A4, or sheet sizes up to US Legal (8.5" × 14"), turning typed or pasted text into pen strokes that look handwritten. Every HandWriter includes the Bantam Tools Studio Text Add-On, a license upgrade that is a separate purchase for other machines. It unlocks Studio's full writing tools: opening text documents, pasting text from the clipboard, the full handwriting font library, Handwriting Defects, and Data Merge for personalized batches of letters. For the full writing workflow, see §6. Writing text; for Data Merge, see §7. Data Merge.

HandWriter also uses different pen-height fields than a plotting machine. Its pens have two heights, Pen Up/Park Height and Pressure Depth, which sets the spring pressure on the pen, and no absolute mode. HandWriter doesn't use Studio's palette-based tools, so the PALETTES tab doesn't appear when it's selected.

Tool Settings section for a HandWriter pen
Tool Settings section for a HandWriter pen

4.3 Changing machines later #

You can change the selected machine at any time from the Machine selection drop-down menu. Switching keeps your loaded artwork or text and applies the new machine's defaults, as §12. The PREPARE tab describes.

The Machine selection menu
The Machine selection menu

Machine Options in Settings lets you set a Maximum Media Size override and adjust machine-control preferences such as auto-connect and upload verification:

Settings → Machine Options

See §17. The SETTINGS tab for details.

Note

With a Maximum Media Size larger than the machine's travel, a job can include motion the machine cannot reach, running the carriage into its mechanical stops. The machines are not designed for that, so keep the override within the machine's travel.

5. From drawing to G-Code #

This chapter follows one drawing from start to finish: opening it, placing it on the paper, choosing the tools that draw it, and saving the G-Code file the machine runs.

The example uses a Bantam Tools ArtFrame™ 2436, and the screens show that machine. The steps are the same on every machine Studio supports; where one differs, a short note says so. Sending the file to the machine and running it are covered in your machine's guide.

5.1 Checking the machine #

The Machine selection menu at the top of the PREPARE tab shows the machine Studio is set up for. For this example, that is Bantam Tools ArtFrame 2436. Switching machines resets the margins and tool assignments to the new machine's defaults.

5.2 Opening a file #

Click OPEN FILE (⌘O / Ctrl+O) and choose the SVG file you want to draw. The drawing appears in the Preview, and the SETUP sub-tab fills in with the settings for the job.

The figures in this chapter show the sample drawing that comes with Studio, so you can follow along exactly.

Following along with the sample

The sample is built into Studio, so it is not opened with OPEN FILE. With no file loaded, the SETUP sub-tab shows a Samples and Generators section; click Sample SVG to load the drawing. If the section is closed, reopen it from the chevron beside OPEN FILE: Open File → Show samples and generators. See §3.7 Samples and generators.

The sample drawing just after opening, on an ArtFrame 2436
The sample drawing just after opening, on an ArtFrame 2436

5.3 Setting the paper size #

In PAPER SETTINGS, choose your paper from the Standard Sizes menu, which lists only sizes your machine can take, or enter its width and height. For this example, choose 8.5" × 11" (Letter).

On an EggBot, these settings describe the object, measured in degrees around it; see the EggBot guide.

PAPER SETTINGS with Letter chosen
PAPER SETTINGS with Letter chosen

5.4 Placing the drawing #

In ARTWORK SETTINGS, set the margins to leave a border around the drawing; this example uses 25.4 mm (1") on every side. Then click FIT TO MARGINS to scale the drawing to the space inside them, and click CENTER. Or double-click the drawing in the Preview to fit and center it in one step. Anything outside the margins shows in red in the Preview and is cropped from the job.

To give the drawing an exact size, see §12.5.3 Setting an exact size.

The sample fitted to the margins and centered
The sample fitted to the margins and centered

5.5 Choosing tools #

A tool is a pen, marker, or brush together with its settings; a toolset is a group of tools for one kind of work. In TOOLSET SETTINGS, choose the toolset that matches your pens. Then, in TOOL ASSIGNMENTS, give each color in the drawing a tool. The sample has one color, so it needs one tool.

For a drawing with several colors, the machine pauses between colors so you can change pens; see §12.8 Tool assignments. On a WaterColorBot, tools are brushes and use a palette; see §8. Painting.

TOOLSET SETTINGS on an ArtFrame
TOOLSET SETTINGS on an ArtFrame

TOOL ASSIGNMENTS for the sample: one color, one pen
TOOL ASSIGNMENTS for the sample: one color, one pen

5.6 Looking over the Preview #

Before you save, look over the Preview. It shows every stroke the machine will draw.

5.7 Saving the G-Code #

Click PROCESS AND SAVE and choose where to save the file. Studio writes the G-Code file, then opens the Setup Sheet, which lists the tools and settings it used. (PROCESS AND SAVE sends nothing to the machine; to get the file onto your machine, see §10. Sending files to your machine.)

The Setup Sheet for the sample
The Setup Sheet for the sample

5.8 Saving the project #

The G-Code file is what the machine draws. To come back to your work and change it later, also save a project: choose File → Save Project As (⇧⌘S / Ctrl+Shift+S). A project file (.btsp) keeps the drawing, its placement, the tool choices, and the other settings, and opening it puts everything back as you left it. See §11.4 Project files.

Part II: Working with Studio

6. Writing text #

This chapter covers the two halves of writing with Bantam Tools Studio™: getting words into Studio, and then selecting fonts and setting the options that control your layout. §13. The TEXT tab describes the TEXT tab and its four sections control by control; what follows is the workflow that runs through them, in the order the sections appear down the tab.

Everything here beyond the first part is part of the Bantam Tools Studio Text Add-On, as is Data Merge, which fills one document from a CSV file to produce a personalized batch and has a chapter of its own. See §7. Data Merge.

6.1 SVG documents that contain text #

When the writing is one part of a larger drawing — a title, a caption, a label on a diagram — the text belongs in the SVG file, placed there in an editor such as Inkscape or Adobe Illustrator. §13. The TEXT tab walks that job end to end, and §20.1 Deciding whether you need a template covers building a reusable .svg template with letterhead, logos, or other fixed artwork around the text.

Once the file is open, the Font face menu in the FONT section lets you write the document in any font in the library rather than in the one the file names. Handwriting Defects, letter spacing, and word spacing all apply to an SVG document's text exactly as they apply to a text document.

One control does not appear: the Font size field is shown only for a text document. An SVG file carries its own type sizes, and Studio writes the text at the size the file specifies, scaled with the rest of the artwork.

6.2 Working with text documents #

A text document is one whose entire content is the words — a .txt file, an .rtf file, or text pasted from the clipboard, whether that clipboard content arrives as plain text, as RTF, or as HTML copied from a browser or an online word processor. There is no template to build and no editor to open first. Most of this text is written somewhere else and brought in finished: a notes app, a word processor, a CRM, an email tool, or a plain text editor.

Word processors such as Microsoft Word and Apple Pages save in their own formats by default (.docx and .pages), and Studio does not open those. Keep writing in the program you know, and save a copy of the finished document in Rich Text Format (.rtf) or as plain text (.txt) for Studio:

Choose .rtf when the document's formatting matters. An .rtf file keeps its type sizes, so a heading stays larger than the body text, and the two scale together when you change Font size (see §6.6 Font size, spacing, and overflow). Underlining is kept too, whether it comes from an .rtf file, from rich text you paste, or from an SVG document, and is drawn by hand in the same pen as the words. A .txt file carries the words alone.

Because there is no SVG template setting the type on the page, the layout is yours to set on the PREPARE tab once the text is in. Studio flows the words into the writing area your margins define, and the Artwork Settings controls place that writing area on the sheet.

A .txt or .rtf file is worth keeping when the same words will be written more than once: a source file is a document, a campaign, or a template you can edit and reopen, rather than something you reassemble from a paste buffer each time. Use the clipboard when the text is finished somewhere else and this is the only time you will write it.

To write a text document:

  1. Bring the text in. For a file, click OPEN FILE and choose the .txt or .rtf file. For text in another application, copy it there, then choose Open from Clipboard in the chevron menu beside OPEN FILE:
    OPEN FILE → Open from Clipboard
  2. Go to the TEXT tab and confirm that Enable Text Rendering is on.
  3. Choose a font in the FONT section, and set Font size below it. Add Handwriting Defects in the card beneath if the document calls for them.
  4. In the SPACING & OVERFLOW section, set Letter spacing, Word spacing, and Text overflow, which sets what happens to text that does not fit. Load a signature in the SIGNATURE section if the document needs one.
  5. Go to the PREPARE tab and set the paper size and the margins. The margins are the writing area, so they decide how much text fits on the page.
  6. Lay the document out on the page with the Artwork Settings controls: FIT TO MARGINS, CENTER, the scale and the offsets, and the overflow behavior. You can also drag the writing in the Preview area to position it by hand.
  7. Confirm the toolset and the tool assignments, so the writing is drawn with the tool you mean it to be drawn with.
  8. Use the Preview to confirm that the document fits within the page size and the margins you set, then click PROCESS AND SAVE.

Studio generates the job from the text as the Preview showed it, laid out inside the margins you set.

A text document laid out inside the margins
A text document laid out inside the margins

Note

With Opening text files opens Text tab turned on in Settings, Studio switches to the TEXT tab by itself when you open a supported text file.

Nothing on the TEXT tab edits the words. To change the wording, change the source — edit the file and open it again, or copy the revised text and use Open from Clipboard.

6.3 Working with batches of text files #

Studio can open several text files at once. A batch holds text files only; SVG files open as a batch of their own (see §12.1 Opening files and file actions). Choose more than one file in the OPEN FILE dialog and Studio loads them as a batch: each file becomes one page in the Preview area's page navigator, and the navigator steps between them.

The page navigator steps between the files in a batch
The page navigator steps between the files in a batch

The settings on the TEXT tab belong to the batch rather than to any one file, so the font, the spacing, the defects, and the signature you set apply to every file in it. Generating the batch writes one output file per source file, each keeping its own base name, along with one Setup Sheet apiece. §11.7 Output file names gives the naming rule in full.

Reload all files from disk, in the OPEN FILE button's chevron menu, rereads every file in the batch at once. Edit the text of several documents in an external editor, click it, and the whole batch comes back current, with the same placement and handwriting variation.

The handwriting variation is per file, and RENDER NEW PREVIEW rerolls the page you are looking at and leaves the rest of the batch as it is. That is what lets you redraw one file whose variation you dislike without disturbing the files you have already approved. As soon as a batch is open, Re-render all pages in the Preview menu rerolls every file in one go.

Data Merge behaves differently with a batch open: the row range collapses to a single Data row field, and every file is merged against that one row. To produce a document per row instead, open a single template file.

Use multiple pages is not offered while a batch is open. If Text overflow is set to Use multiple pages when you open a batch that includes a text file, Studio switches it to Scale text down only and reports Opened file batch. Text overflow is set to: Scale text down only. The setting stays there after the batch closes.

6.4 Font selection #

The FONT section holds the choice of font. Open it and use the Font face menu to browse the library; the menu accepts typing as well as clicking, so a few letters narrow a long list to the face you want. The section's header names the current selection, which is enough to check the font on a document you set up last week without expanding the section. Choosing a face redraws the Preview area in it, so styles can be compared on screen before any of them is committed to paper.

Typing in Font face narrows the list
Typing in Font face narrows the list

The fonts in the library are designed for writing and plotting workflows, and are intended to be drawn as paths rather than filled the way a screen or printer font is.

To install a font of your own, click SELECT beside Additional font and choose an SVG font file — a digitized version of your own hand, or a face specific to your brand. Studio also makes every other SVG font file in that same folder available, so a folder of faces is installed by picking any one of them. The file name appears beside the button, with a trash button to clear the selection. Clearing it removes those fonts from the list; the files themselves are not changed.

The FONT section
The FONT section

For pen plotting, writing, or painting, a single-stroke font is the efficient choice: the tool travels each letter once rather than tracing its edge, which means less motion and less time on every page. A regular computer font, such as a TrueType or OpenType font, is an outline font, and a pen writes each of its letters as a hollow shape.

The Preview helps you decide which face you like the look of. Faces also differ in how compact they are and how readable they stay at small sizes, and a short sample on paper shows both.

6.4.1 Letting the document choose the font #

The font you choose applies to the whole document. A document can instead name its own fonts, and Studio will honor them: where a piece of text asks for a font by name, and the library holds a stroke font that matches that name, Studio writes that text in the matching stroke font rather than in the font selected in Studio.

This is how a document gets more than one font. One font choice cannot give a heading one face and the body another; naming the fonts in the document can. Set the heading in one face and the body in another in your editor, and both survive into the writing.

It also settles a mixed batch. When you open several documents at once, each one brings its own fonts, so a batch of letters that are not all in the same hand needs no per-file adjustment. See §12.1 Opening files and file actions.

Text that names no font, or names a font that is not in the library, is written in the font currently selected in Studio.

6.4.2 Some sources of stroke fonts #

The library that ships with Studio is not the whole supply. Two sources add to it, and they solve different problems: one sells faces drawn by a type designer, the other turns your own handwriting into a font.

Quantum Enterprises sells commercial stroke fonts, as stock faces and as custom work, at https://quantumenterprises.co.uk/slf. They are a third party; Bantam Tools does not sell or support their fonts.

A line of text written in Premium Ultra 25SL, from Quantum Enterprises
A line of text written in Premium Ultra 25SL, from Quantum Enterprises

The same text in Premium Ultra 79SL
The same text in Premium Ultra 79SL

Their faces come as matched pairs, a TrueType file and an SVG file of the same name. That pairing is what makes the document-chosen font behavior above useful in practice: install the TrueType file on your computer, set type in it in your editor, and Studio writes that text in the matching stroke font without any further setup. Custom work includes fonts drawn from a sample of your own handwriting.

Most of their faces also carry several drawings of each letter. Studio picks among those as it writes, so a letter repeated in a word is not repeated identically — which is a different kind of variation from the Handwriting Defects sliders, and the two combine.

That substitution is done by a service Quantum Enterprises runs, called the Scriptalizer. A font declares itself compatible, and Studio then sends the document's text to that service as part of rendering and writes what comes back. It needs an internet connection: without one, the text is still written, just without the substitution. Nothing turns it on — a compatible font uses it, and the fonts that ship with Studio are not compatible.

The second source is Bantam Tools Font Maker, an iPad app that builds a font from your own handwriting, written with an Apple Pencil. It is at https://bantam.tools/fontmaker, and it has a user guide of its own.

You write each character, edit and preview the result in the app, and export an SVG single-stroke font, the format Studio writes with. Writing, editing, and previewing are free; exporting is a one-time in-app purchase.

A commercial face gives you a type designer's hand; Font Maker gives you your own.

6.5 Handwriting Defects #

Writing that comes out perfectly even reads as a machine: straight rows, evenly spaced, every letter the same size as the last. Plotted carefully with a good pen it is still handsome, but the layout suggests a printer rather than a hand.

Handwriting Defects counters that. With Enable on, Studio adds intentional random variations to the text as it renders it, of the kinds that turn up in real handwriting — rows that are not quite level, letters that sit a little high or low, spacing that opens and closes. The result stays neater than most people write, and stops announcing that a machine laid it out.

The toggle is off until you turn it on, so a document is written plainly unless you ask for otherwise. (Default: off) The slider beside it sets how much variation the writing gets, from 0 to 100. (Default: 20)

The HANDWRITING DEFECTS section, with its single slider
The HANDWRITING DEFECTS section, with its single slider

To adjust each kind of variation separately, click the arrow at the left of the slider. Six sliders take its place, one for each defect. Click the arrow again to return to the single slider, which then moves all six together and keeps the differences between them.

The six sliders, shown by clicking the arrow. Each is set differently here.
The six sliders, shown by clicking the arrow. Each is set differently here.

Every sample in this section is the same block of text, so the sliders can be compared against one another and against the writing with Handwriting Defects off, shown here.

Each sample that follows sets one slider to 100, its maximum, with the others off.

Handwriting Defects off
Handwriting Defects off

Each of the six sliders sets one kind of variation:

  • Line spacing: Varies the vertical gap between lines, so they do not sit on a perfect grid.

The sample shows the Line spacing slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Line spacing at 100 (exaggerated)
Line spacing at 100 (exaggerated)
  • Baseline jitter: Nudges each letter a little above or below the baseline.

The sample shows the Baseline jitter slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Baseline jitter at 100 (exaggerated)
Baseline jitter at 100 (exaggerated)
  • Indent: Varies where each line begins along the left margin.

The sample shows the Indent slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Indent at 100 (exaggerated)
Indent at 100 (exaggerated)
  • Kerning: Loosens and tightens the gaps between neighboring letters.

The sample shows the Kerning slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Kerning at 100 (exaggerated)
Kerning at 100 (exaggerated)
  • Letter size: Makes each letter a little larger or smaller than its neighbors.

The sample shows the Letter size slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Letter size at 100 (exaggerated)
Letter size at 100 (exaggerated)
  • Scrunch: Where a line ends just short of fitting the next word, it leaves an awkward gap. Writing by hand, you might squeeze that word in anyway, narrowing the letters as you run out of room. Scrunch does the same: it tightens letters and spaces progressively toward the end of a line, more and more as the space runs out, to fit one more word.

The sample shows the Scrunch slider at 100, exaggerated to make its effect easy to see. In most documents, 15 to 20 works well.

Scrunch at 100 (exaggerated)
Scrunch at 100 (exaggerated)

Start small. A little variation reads as a hand; a lot reads as an unsteady one, and the sliders reach well past the point where writing stays comfortable to read. The single slider starts at 20, which is a good place to begin. Raise or lower it a little at a time and see what changes in the Preview. For finer control, open the six sliders with the arrow and change one at a time.

The variation comes from a random pattern rather than from a fixed rule, so two renders of the same text differ. RENDER NEW PREVIEW, in the Preview's header, rerolls that pattern and draws the writing again, which is how you look at several versions of a document and keep the one you like.

The same text with every defect at its default strength
The same text with every defect at its default strength

None of the six sliders is a size control, and none of them changes the writing area. They do change how much text fits on a page, though, which is why a document's page count can move when you raise them; see §6.7 Multipage layout.

6.6 Font size, spacing, and overflow #

Three things together decide whether a document fits the page it has: the size of the type, the spacing between letters and words, and what you choose for text that runs past the margins.

Font size sits in the FONT section, below the font face, and appears for a text document only. It is a text field with a menu of common sizes beside it, from 14 pt up to 60 pt, and it accepts any size you type. (Default: 24 pt) When an .rtf file or HTML from the clipboard brings a size of its own, opening it sets the field to that size, and the size joins the menu marked (document), so the size the document was written at is one click away and is not mistaken for a preset. The field sets the document's base size, usually its body text. If the document came in with styling that sets some parts in different sizes, text in the whole document is scaled proportionally when you change the text size setting in Studio. For example, in a document with 12 pt body text and an 18 pt heading, setting the field to 24 pt draws the heading at 36 pt.

The Font size menu, with an .rtf file's own size marked (document)
The Font size menu, with an .rtf file's own size marked (document)

The size in the field is the size the body text is actually drawn at. That is usually the size you entered, but when an overflow setting shrinks the text to fit, the field shows the smaller size the writing is rendered at rather than the larger one you requested, and the label above it changes from Font size to Font size (auto). That relabeling is the reliable way to tell at a glance whether you are choosing the size or Studio is. Hovering the field explains which of the two is happening and, when Studio has scaled the text down, what it scaled it down from.

Hovering Font size (auto) explains how the size was chosen
Hovering Font size (auto) explains how the size was chosen

Font size (auto) shows Studio chose the size
Font size (auto) shows Studio chose the size

The SPACING & OVERFLOW section holds the rest. Both spacing controls are percentages of the font's own spacing, so 100% is the font as its designer drew it:

  • Letter spacing: Sets the space between letters, from 1% to 400%. (Default: 100%)
  • Word spacing: Sets the space between words, from 1% to 600%. (Default: 100%)
The SPACING & OVERFLOW section
The SPACING & OVERFLOW section

The Text overflow menu sets what happens when the text does not fit the writing area:

  • Do not scale text: Draws the text at exactly the size you set, even where that runs past the margins. (Default)
  • Scale text down only: Shrinks text that is too large, and leaves text that already fits at the size you set.
  • Scale text to fit: Resizes the text up or down so that it fills the writing area, whether the text was too large or too small to begin with. The size is Studio's to choose, and the field goes read-only and is relabeled Font size (auto).
  • Hide overflowing text: Draws the text at the size you set and does not plot anything past the margins.
  • Use multiple pages: Keeps the size you set and continues the document onto as many pages as it needs. Offered only when a single document is open. See §6.7 Multipage layout.
The Text overflow menu
The Text overflow menu

Scale text down only never makes text larger, so a short note set at 18 pt stays at 18 pt on a big sheet; Scale text to fit would grow the same note until it filled the writing area, which is the right behavior for a quotation on a poster and the wrong one for a letter.

Example: a note set at 24 pt whose last two lines fall below the bottom margin. Under Do not scale text, those two lines are drawn past the bottom margin. Under Scale text down only, Studio shrinks the whole document until it fits — to something like 21 pt — and the label reads Font size (auto): 21 pt. Under Hide overflowing text, they are not drawn at all, though they are still in the document. Under Use multiple pages, they begin a second page, still at 24 pt.

The same menu appears on the PREPARE tab, in Artwork Settings, where the two are one setting shown twice — changing either changes both. For an SVG document that position in Artwork Settings holds the Content Bounds and Document Bounds choice instead; a text document has no artwork whose edges could be measured, so the overflow menu takes the control's place. The Scale field beside it goes read-only for the same reason, reporting the scale the margins produced rather than accepting one.

Note

Studio fits the text to the writing area your margins define. To give a document more room, change the paper size or the margins on the PREPARE tab.

6.7 Multipage layout #

Use multiple pages is the fifth choice in the Text overflow menu when a single document is open, and the only one that lets a document run past a single page. The other four fit the text to the page it has — by shrinking it, letting it run past the margins, or hiding what is left over. This one keeps the text at the size you chose and continues the document onto a second page, a third, and so on, until every word has been drawn.

The margins you set on the PREPARE tab apply to every page just as they do to a single one, and nothing else about the layout changes from page to page.

Select Use multiple pages and Studio lays out the first page and shows it in the Preview area, with the rest of the pile drawn behind it so you can see at a glance that the document runs long. By default the pile sits at a slight angle, as a stack of paper would; Multipage: Neaten Preview Pile, in the Preview menu, squares it up.

The remaining pages fill in the background while you keep working, and the status line above the preview counts them as they arrive. The total carries a tilde while it is still an estimate, and loses it once every page has been laid out.

A page navigator appears below the preview as soon as the document runs to more than one page. The inner arrows step one page at a time, the outer arrows jump to the first or last page, and typing a page number into the field goes straight there. You can jump past the pages Studio has laid out so far — the navigator shows Rendering… and waits for the background pass to reach the page you asked for.

Note

In a multipage document, RENDER NEW PREVIEW rerolls the whole document rather than the page you are looking at, so every page is redrawn from one fresh random pattern and the handwriting stays consistent throughout.

Each document is limited to 100 pages. Past that, Studio reports Text layout error: each document is limited to 100 pages beside the Preview and does not generate output; see §19. Troubleshooting.

Generating a multipage document writes one G-Code file per page into the folder you choose when the batch starts, each name carrying a page suffix: Letter_p1, Letter_p2, and so on. A document that fits on one page takes the name you entered, with no suffix. Studio writes one Setup Sheet per page as well. For the naming rule in full, see §11.7 Output file names.

A document flowing onto several pages
A document flowing onto several pages

6.7.1 Page breaks #

Choosing Use multiple pages reveals a Page breaks menu beneath it, which decides where one page ends and the next begins:

  • Fill page: Fits as much text on each page as it will hold, breaking wherever the page runs out of room, even part-way through a paragraph. (Default)
  • Break at paragraphs: Never splits a paragraph across a page break. A paragraph that does not fit moves whole to the next page, which can leave a conspicuous gap at the bottom of the page it left.
  • Smart paragraphs: Prefers to break between paragraphs, as Break at paragraphs does, but splits a long one when keeping it whole would waste most of a page. When it does split a paragraph, it avoids stranding a single line at the top or the bottom of a page.
Page breaks appears with Use multiple pages
Page breaks appears with Use multiple pages

Fill page uses the fewest sheets, and suits continuous prose, where a paragraph carrying over a page break reads naturally. Break at paragraphs suits a document whose paragraphs are meant to be taken in together — recipe steps, numbered terms, short entries in a list — and it will spend paper to keep them that way. Smart paragraphs sits between the two, and is the one to reach for on a long document: it keeps paragraphs whole where that costs little, and splits them where the alternative is half an empty page.

The Page breaks menu
The Page breaks menu

None of the three changes the type size or the page count on its own account; they change only where the breaks fall, and the page count moves as a consequence.

Note

Changing the page break setting re-flows the document from the first page. Text moves between pages, and the page count may change with it, so it is worth settling the setting before you review individual pages.

6.7.2 How text size is determined #

Your Font size setting is used as entered, which is the whole point of this mode and what separates it from the other four. They hold the document to one page and let the text size give way; this one holds the text size and lets the page count give way.

The field stays editable here, and its label stays Font size. Only Scale text to fit takes the size out of your hands, and it says so by relabeling the field Font size (auto).

Four things together decide how much text a page holds, and so how many pages a document runs to:

Example: a letter of about 1,500 words in BNTM Speculation on 8.5" × 11" (Letter) paper with 25 mm (1") side and top margins runs to about 11 pages at 24 pt. At 16 pt, often a better fit for a letter, the same text runs to about 5 pages, with no other setting touched. Another font at the same size can run longer or shorter.

Note

Studio places at least one line on every page, so a font size too large for the writing area produces many pages of one line each.

If text comes out at the wrong size, wraps unexpectedly, or a font or signature does not appear, see §19. Troubleshooting.

7. Data Merge #

Data Merge turns one document and one spreadsheet into a batch of personalized documents — a thank-you note per donor, a place card per guest, a certificate per graduate. This chapter describes everything the feature does, from merge fields through the techniques that let one sheet carry several records. Data Merge lives on the DATA MERGE sub-tab of the TEXT tab, described in §13. The TEXT tab.

7.1 What Data Merge does #

If you have run a mail merge in a word processor, the idea is the same: write the document once, mark the places where the personal details go, load a spreadsheet saved as a CSV (comma-separated values) file, and let the software produce one copy per row.

The marks are called merge fields: field names wrapped in double curly braces. A document might read:

Dear {{first_name}},

Thank you for your recent order of {{product}}.

Warmly,
{{sig}}

With a CSV file whose columns are first_name and product, that document becomes one written page per row, each carrying its own name and its own product, and each signed. {{sig}} is not a merge field, though it is written like one: it is a signature command, which Studio fills from the signature file or the font, never from the CSV file. See §13.4 Signatures.

The names sig, sigalt, and siginit are reserved for the signature commands, so they cannot be used as CSV column names. Studio ignores a column with one of those names, in any capitalization; give it another name to use it as a merge field.

To set up a merge:

  1. Write the document with merge fields where the personal details belong, and bring it into Studio. A .txt file, an .rtf file, text from the clipboard, or a designed .svg template all work; §6. Writing text covers the first three and §20. Appendix: SVG templates in Inkscape covers the fourth.
  2. On the TEXT tab, confirm that Enable Text Rendering is on, then open the DATA MERGE sub-tab and turn on Enable Data Merge. (Default: off)
  3. Click SELECT beside CSV data file and choose your CSV file. The file name appears beside the button, with a trash button to clear it.
  4. Open the CSV DATA PREVIEW section and read its summary. It reports how many rows and columns Studio found, how many of your merge fields it matched to columns, and how many documents the batch will build.
  5. Turn on Preview merge result to see real data in the Preview area instead of the raw merge fields. (Default: off)
  6. Set Start row and End row to choose which rows of the CSV file to use.

The CSV DATA PREVIEW section now names the number of documents the batch will build, and the Preview area shows the first of them with real data in place of the merge fields. That count is the checkpoint: if it is not the number you expected, correct the row range or the CSV file before going on.

The template before merging, its merge fields visible
The template before merging, its merge fields visible

The same document with Preview merge result on
The same document with Preview merge result on

Handwriting variation is drawn separately for each merged document, so no two come out identical even where the text is. RENDER NEW PREVIEW, in the Preview's header, rerolls the document you are looking at and leaves the others alone. Once the batch runs to more than one document, Re-render all pages in the Preview menu rerolls every document in the merge at once.

To generate the batch:

  1. Go to the PREPARE tab and set the paper size, the margins, the layout, the toolset, and the tool assignments, exactly as you would for any other document. See §12. The PREPARE tab.
  2. Optionally, choose how the output files are named with the Merge File Naming setting; by default they are numbered in sequence. See §11.7 Output file names.
  3. Click PROCESS AND SAVE and choose a folder.

Studio writes one output file per document into that folder, named according to the mode you chose.

DATA MERGE sub-tab with a CSV file loaded
DATA MERGE sub-tab with a CSV file loaded

For a first merge, try the included sample: with no file open, click Sample CSV under Samples and Generators on the PREPARE tab. (If those buttons are not showing, choose Show samples and generators from the menu beside Open File.) Studio opens an address template, loads a five-row CSV file to fill it, and turns on Data Merge, so you can step through the finished documents in the Preview. A template of your own with a handful of merge fields and a few rows of data works the same way, and conditional text and future rows, described below, build on that sequence.

7.2 CSV files and merge fields #

The first row of the CSV file must be a header row: a row that holds not data, but a unique name for each column. Those header names become the field names you write in merge fields. A column headed first_name is written in the document as {{first_name}}.

The columns can be in any order, which need not match the order the fields appear in your document, and you don't need to use every column. The file needs at least two columns.

Tip

If you plan to use only one column, add a second column that numbers the rows: 1, 2, 3, and so on.

A spreadsheet's header row, a column of data, and a data row. Data rows are counted from the first row under the header, so spreadsheet row 7 is data row 6.
A spreadsheet's header row, a column of data, and a data row. Data rows are counted from the first row under the header, so spreadsheet row 7 is data row 6.

The CSV DATA PREVIEW table, its columns named by the CSV file's header row
The CSV DATA PREVIEW table, its columns named by the CSV file's header row

Matching ignores letter case and surrounding spaces, so a header of First_Name or first_name still fills {{first_name}}. It does not ignore anything else — address2 and address 2 are two different names, and a merge field that names a column the file does not have is reported below the CSV DATA PREVIEW section as a missing column (for example, Data merge error: CSV file missing column: frist_name) rather than filled with nothing. The signature commands {{sig}}, {{sigalt}}, and {{siginit}} are never reported this way, since they do not read the CSV file.

Studio also trims leading and trailing spaces from the merged values themselves. There is no toggle for this; it always runs, so a stray space at the front of a spreadsheet cell does not travel into the writing.

You can create and edit a CSV file in almost any spreadsheet application; Microsoft Excel, Numbers, Google Sheets, and LibreOffice all export CSV files. CSV is also one of the most common formats for moving data between databases and other applications, so an export from an online store or a donor database works as well. Studio reads CSV files saved in UTF-8 encoding, as most spreadsheet applications export them. A cell holding a stand-in value such as N/A is written out literally, as "N/A"; leave the cell empty to leave its field blank.

Tip

Short, lowercase header names — first_name, last_name, address1, address2, city, state, zip — are easier to type into a template and easier to read back when a field comes out blank.

7.3 Choosing which rows to use #

Start row and End row decide which part of the CSV file the batch draws on. They appear when one file is open; with several open at once the pair collapses to a single Data row field and every file merges against that one row, as §6. Writing text describes. Both count data rows rather than spreadsheet rows: the header row is not row 1, the first record is. Both fields start at 1 and will not go below it, so a fresh merge begins at the first record, and you set End row to the last record you want. Only rows from the start row through the end row are merged, and everything outside that range is ignored.

With more than one file open, the row range collapses to a single Data row field
With more than one file open, the row range collapses to a single Data row field

A template does not have to contain merge fields at all. With none, every document in the range carries the same text, and the range becomes a copy count: Start row 1 and End row 25 produce 25 copies of the same page.

This is a common way to write a batch of nearly identical pages. With Handwriting Defects on, or in a font that carries several drawings of each letter, each copy is written a little differently, as a hand would; see §6.5 Handwriting Defects and §6.4.2 Some sources of stroke fonts.

The range also lets you pick up where a run left off, or write a single record again: set Start row and End row to the rows you want.

A batch holds up to 250 documents. When a range asks for more, Studio builds the first 250, and the CSV DATA PREVIEW summary shows it: "250 documents (limited to 250)". For larger jobs, see §19. Troubleshooting.

7.4 Referencing future rows #

An ordinary merge uses one CSV row per generated page. Studio can also let one page draw on several rows at once, which is what a sheet holding more than one finished piece needs: two foldable 5" × 8" greeting cards on a US Letter or A4 sheet written on Bantam Tools HandWriter®, or several 4" × 6" cards on a 24" × 36" sheet drawn on an ArtFrame™. Each card wants a different recipient, and all of them are one generated page.

There are two ways to say so, and they suit different templates.

The ++ method names a row offset inside the merge field. {{first_name}} reads the current row, {{first_name++1}} reads the next row, and {{first_name++2}} the row after that. Three cards on one sheet, each in its own text area, begin:

Dear {{first_name}},
Dear {{first_name++1}},
Dear {{first_name++2}},

Starting at row 1, the first sheet draws on rows 1, 2 and 3; the next sheet begins at row 4 and draws on 4, 5 and 6. Each merge field states which row it reads, which makes a grid of fixed positions straightforward to check and straightforward to fix when one card comes out wrong.

One generated page holding three addresses, each merge field naming its own row
One generated page holding three addresses, each merge field naming its own row

The {{nextrow}} method advances the row instead of naming it. Every merge field after a {{nextrow}} reads one row later than the merge fields before it:

Dear {{first_name}},
Thank you for your support.
{{nextrow}}
Dear {{first_name}},
Thank you for your support.

The first greeting takes the current row, {{nextrow}} steps forward, and the second greeting takes the next one. The template reads top to bottom as ordinary text, with no offsets to keep in your head, which is why a two-card folded layout or any sequence of identical repeated items is usually easier to maintain this way.

A sheet of address labels is the case this suits best. Every label carries the same block, ending in {{nextrow}}, so each one steps to the following record and a page of labels comes out of a page of the CSV file. Keep each label's fields in one text area, ending in {{nextrow}}: Studio steps through merge fields in the order the SVG file stores them, which can differ from their order on the page.

Four labels from a label-sheet template. Each block is identical and ends in {{nextrow}}, so each label takes the next record.
Four labels from a label-sheet template. Each block is identical and ends in {{nextrow}}, so each label takes the next record.

The label outlines in that template are ordinary artwork, so they would be drawn along with the addresses. Put guides like those on a documentation layer, named with a leading %, and Studio leaves them out. See §20. Appendix: SVG templates in Inkscape.

{{nextrow}} is the simpler choice for most templates. Use ++ when the layout is a grid of fixed positions and you want each field to name its own row, and use one method or the other within a template.

A page is built only when all the rows it draws on exist, so leftover rows at the end of the file are skipped. With a sheet of three labels per page and a CSV file of five addresses, Studio builds one page holding the first three addresses, and skips the last two. The summary under the CSV DATA PREVIEW section names them: Rows 4–5 are not used; each document uses 3 rows. The same summary gives the document count, where each sheet is one document, and the last document in the Preview shows the final addresses the batch will write.

7.5 Conditional text #

Some fields are filled for some records and empty for others: a company name, a second address line, a suite number, an attention line, a membership year, a donation amount, a custom note. Conditional text lets you attach words to such a field so that the words appear only when the field has data.

The pattern puts the extra text in double square brackets, inside the merge field, before or after the field name:

{{[[text before]]field_name[[text after]]}}

So {{[[Dear ]]First}} writes Dear Abigail when First holds Abigail, and writes nothing at all — not even the word Dear — when First is empty. Text after the field works the same way: {{memberyears[[ years as a member]]}} writes 5 years as a member when the field holds 5, and stays silent when it does not.

The brackets and the field name share one pair of double braces, so write {{[[Dear ]]First}}, not {{[[Dear ]]{{First}}}}. A merge field inside another is reported as a missing column, with a reminder of how to write it.

The same brackets can carry a line break. \r stands for a return, and it can appear in fixed template text as well as in conditional text. It is how a field inserts a line break without the CSV cell having to visibly contain multiple lines — the break lives in the template, where you can see and edit it, rather than inside a spreadsheet cell:

{{First}} {{Last}}\r{{Address1}}\r{{City}}, {{State}} {{zip}}

Note

To write a literal \r, for example in C:\reports, put the backslash in double curly braces: C:{{\}}reports. This special case keeps the backslash from turning into a return. {{\}} is not a merge field, since a lone backslash can't be a column name, so it needs nothing in the CSV file.

Combining the two solves the classic address-block problem. An optional second address line written plainly leaves an empty line whenever it is blank. Attach the return to the field instead:

{{Address1}}{{[[\r]]Address2}}
{{City}}, {{State}} {{zip}}

Now the return and the value arrive together or not at all, and a record with no second address line closes up cleanly. A block that handles both personal and company addresses extends the same idea:

One address template, drawn for a record that has a second address line
One address template, drawn for a record that has a second address line

The same template for a record with none: the line and its return are both absent
The same template for a record with none: the line and its return are both absent

{{company[[\rAttn: ]]}}{{First}} {{Last}}
{{Address1}}{{[[\r]]Address2}}
{{City}}, {{State}} {{zip}}

Two conditional elements are at work. The first puts a return and Attn: after a company name, but only when there is a company name. The second puts a return before the second address line, but only when there is one, so a record without it does not leave a blank line behind.

The same three lines of template can therefore come out as different as these:

Ruth Okonkwo                   Harbor Line Supply
1140 Ferry Street              Attn: Ruth Okonkwo
Portland, ME 04101             1140 Ferry Street
                               Building 4
                               Portland, ME 04101

7.6 Data Merge with multipage documents #

Data Merge produces one document per CSV row, and Use multiple pages runs one document across as many pages as its text needs. Turn on both and they combine: each merged document flows onto its own run of pages, and the job becomes a grid of documents and pages rather than a single stack of sheets. Overflow behavior is set in §6.6 Font size, spacing, and overflow, and flowing is described in §6.7 Multipage layout.

Studio paginates each document separately, so they will rarely come out the same length. A row whose text runs long produces a four-page document; the row after it may produce one page. Nothing pads a short document out to match a long one.

Note

The CSV DATA PREVIEW section's summary counts documents, not sheets of paper. If your documents flow onto multiple pages, refer to the page count in the page navigator below the Preview.

The preview navigator gains a second axis for this combination, and shows three controls instead of one:

The navigator's Document, Page, and Overall controls
The navigator's Document, Page, and Overall controls

Both counts carry a tilde while Studio is still flowing. The Page count settles first, for the document you are on, and the Overall count settles once every document has been flowed to its end.

RENDER NEW PREVIEW rerolls the document you are looking at and leaves the rest alone, so you can redraw a document whose variation you dislike without disturbing a batch you have already approved. Re-render all pages, in the Preview menu, rerolls every document in the job.

The 100-page limit applies to each document separately rather than to the job as a whole. One over-long row stops that document at page 100 and blocks generation until it fits; the other documents are unaffected. The job carries its own limit of 2,500 pages in total, and that one behaves differently: Studio builds as many whole documents as the budget allows, drops the rest, and reports how many it built, rather than refusing to generate. (If your work runs up against either limit, contact us at support@bantamtools.com.)

Output is named document first, then page: a merge of Letter over a column of names produces Letter_Alice_p1, Letter_Alice_p2, Letter_Bob_p1, and so on. The document suffix follows the Merge File Naming setting, and the page suffix is always _p and the page number. Setup Sheets come one per document, from its first page, rather than one per page — the sheets for the pages of a single document would otherwise be near-identical. See §11.7 Output file names.

7.7 Generating a batch #

A merge batch generates the same way any other job does, through PROCESS AND SAVE and the folder you choose when it starts.

Before you generate, step through the documents in the Preview with Preview merge result on. Look at a record with its optional fields filled and one with them empty, and at the one with the longest name or address. Then generate the batch, and write the first sheet on the machine before you write the rest: it shows the fit and spacing with the pen and paper you will use.

For sending the finished files to a machine over microSD, USB, or WiFi, see §10. Sending files to your machine. For the export formats PROCESS AND SAVE can produce and the Setup Sheets that come with them, see §11. Exporting output.

Tip

Save a production merge as a project. The project keeps the template, the CSV file, and the settings together, so the next run of the same job starts where this one left off; see §11.4 Project files.

If a field comes out blank, the wrong row lands in a slot, or a batch is named unexpectedly, see §19. Troubleshooting.

8. Painting #

This chapter covers painting with brushes and palettes: how painting differs from drawing with a pen, the painting toolsets and tool macros, palettes, and how to test a painting tool.

8.1 What painting means #

Painting is plotting with a brush. The machine follows the paths you define exactly as it does with a pen. What changes is that the tool carries paint: the brush returns to a palette to reload, and the materials have a say in the mark it leaves.

The machine moves the brush precisely and repeatably. Where the brush goes, how fast it moves, and how often it returns to the palette to reload all come from your artwork and the brush's settings.

That repeatability is what makes the physical side workable. Paint flows, water spreads, paper absorbs, and brushes change character as they move. Because the motion underneath is the same every time, you can run a file again and see how a change in speed, stroke order, or refill behavior shows up on the paper. Each run carries its own character, which is part of the medium.

Artwork is defined by SVG paths, and the Preview shows the motion those paths produce — where the brush travels and in what order — so you can check the plan before any paint reaches the paper. The painting itself emerges as the machine works.

To make paint-ready SVG artwork from a photograph, use the Image Processor; see §9. The Image Processor.

You define paths, stroke order, speed, and refill behavior, and the materials do the rest.

8.2 Key painting concepts #

When painting, several concepts become more important than they are in pen plotting.

8.2.1 Stroke and sort order matter #

Earlier strokes can wet the paper or deposit pigment that later strokes interact with. The order of colors, layers, or groups matters on the paper and on the brush itself.

Small amounts of pigment can remain on the brush between strokes and refills. Painting from lighter to darker pigments often produces more predictable results, especially in automated workflows where the machine is not paused for tool changes.

8.2.2 Speed affects saturation #

Slower motion keeps the brush in contact with the paper longer, usually depositing more paint and producing darker strokes. Faster motion reduces contact time, producing lighter strokes with less pigment transfer.

Speed also changes how water and pigment spread. Slower strokes encourage pooling, blending, and softer edges, while faster strokes give drier marks with sharper transitions. Painting tools therefore usually run slower than pen tools.

8.2.3 Refilling is intentional #

Returning to the palette is part of the painting process, not an interruption. How and when a tool refills affects saturation, consistency, and how a layer develops over time.

Each brush tool has its own Refill Mode setting, with three choices: No Refills, Refill by Distance, or Refill by Stroke. Refill by Distance returns the brush to the palette each time it has painted a set distance, wherever that falls: at the start, the middle, or the end of a stroke. After the refill, the brush returns to the exact point where it left off and continues the stroke. Refill by Stroke refills only between strokes, before every stroke that the Refill After Strokes count comes around to, so each stroke is painted in one pass however long it is. See §14.5 Editing an individual tool for the full field description.

The two refill modes trade consistency for character. Refill by Distance keeps the paint load even. Refill by Stroke lets long lines thin out as they go, which looks more like a hand-painted mark. Shorter refill distances, or fewer strokes between refills, give more even strokes, and longer ones let the paint fade and evolve across a layer.

Refills also change the palette itself over a long painting. Dipping in water before every refill carries water into the paint and gradually dilutes it, while letting a pan dry out partway through a layer makes the strokes that follow darker and more saturated.

Different toolsets manage refill behavior differently. Some use water before or after pigment. Some scrape excess paint. Some allow pigment to evolve over repeated strokes.

8.3 Basic painting usage #

To begin a painting workflow:

  1. Select the appropriate machine.
  2. Open an SVG file.
  3. Set paper size and margins.
  4. Select a painting toolset.
  5. Select a palette layout.
  6. Assign tools to colors, layers, or groups.
  7. Preview the motion.
  8. Generate and send the job.

Painting behavior is enabled when a palette layout is selected. Selecting WaterColorBot loads a default 12 Pan / Crayola palette automatically: eight paint pans in one column, for a Crayola watercolor set, and four water basins beside them, but you can pick a different layout, such as 8 Pan or 16 Pan, from the palette selector. The selected toolset and palette layout together determine the macro behavior used during painting.

Palette menu with 12 Pan / Crayola selected
Palette menu with 12 Pan / Crayola selected

8.4 Toolsets for painting #

A painting toolset is more than a list of colors. It defines a reusable painting system.

A toolset may include:

Preset painting toolsets provide starting points for common watercolor workflows. They can be used as provided or duplicated and modified.

8.5 Loaded vs. balanced #

A loaded brush goes directly from paint to paper, carrying the maximum amount of pigment.

A balanced brush returns to water after loading with paint, adjusting the pigment-to-water ratio before painting.

Balancing helps control saturation, consistency, and repeatability.

8.6 Wet vs. scraped #

A wet brush goes straight to the paper after being loaded or balanced, retaining excess moisture and pigment.

A scraped brush is lightly wiped on the edge of the palette to remove excess paint and water.

Scraping helps prevent drips, pooling, and unintended bleed.

Wet-versus-scraped differences come from the brush's tool macros and how it loads paint.

8.7 Preset painting toolsets #

Each painting machine includes preset painting toolsets, listed in its section of the tool setup reference: for the ArtFrame, see §15.1.1 Preset toolsets; for the WaterColorBot, see §15.4.1 Preset toolsets. Most hold one brush tool for each paint color, plus a water tool, and differ in how the brush takes up paint before each stroke: loaded or balanced, then wet or scraped, as described above. Others serve one purpose, such as a brush pen that carries its own ink. Use a preset as it is, or copy it into a toolset of your own and change it.

8.7.1 Watercolor brush (water) #

Most preset toolsets also include a tool named Watercolor brush (water). It paints with water only, for wet-on-wet effects. Keep Hold Position on Tool Change enabled for this tool (see §14.5 Editing an individual tool) and confirm the water is clean before starting a new color, layer, or group. For wet-on-wet painting, turn Hold Position on Tool Change off for the color tools that follow the water, so that the machine goes on to paint while the water layer is still wet.

8.8 Tool Macro Setup #

Tool Macros define how a brush tool interacts with the palette before, during, and after painting: where it dips, how many times, how deep, and how often. Each brush tool has its own macros, set in the Tool Macro Setup section, below Tool Settings when you select the tool in the Tool Library. The section appears on ArtFrame and WaterColorBot, for brush tools. See §14. The Tool Library.

There are four macro stages, each run at a different point in painting:

A refill is due according to the tool's Refill Mode: after a set distance or a set number of strokes; see §14.5 Editing an individual tool. Each refill runs its stages in order: Pre-Refill, then Refill, then Post-Refill. With Refill Mode set to No Refills, only Prime/Wash can be used, and the other three stages are grayed out with the message "Refill behaviors disabled."

Tool Macro Setup for a brush tool set to No Refills: only Prime/Wash is available
Tool Macro Setup for a brush tool set to No Refills: only Prime/Wash is available

Painting with a tool therefore has two phases. The tool starts with Prime/Wash, once. It then repeats a loop of painting and refilling (Pre-Refill, Refill, Post-Refill, then paint) until its strokes are done, without returning to Prime/Wash.

The stages are not limited to plain rinses. A Pre-Refill that dips in a second color mixes paint on the brush, and running it only every few refills builds a gradual shift in color across a layer. A stage can use several locations, for mixing, balancing, or blending.

Aside

Think of Tool Macros as choreography. The order and frequency of dips, refills, and returns define the behavior of the brush over time. Two tools can use the same brush and the same paints and still paint very differently, because a tool describes a behavior as much as a brush.

Tool Macro Setup section for a WaterColorBot brush tool
Tool Macro Setup section for a WaterColorBot brush tool

8.8.1 Assigning palette locations to a tool #

A palette's wells are numbered locations. You choose which locations each tool uses for each stage, to match the paint and water you put in them. Assign them with the palette preview on the left of the Tool Macro Setup section:

  1. Open the Tool Library (⌘3 / Ctrl+3) and select a brush tool. Select the tool itself, not its toolset, since locations are set one tool at a time.
  2. Choose a palette from the Select a palette to view/edit menu. Studio shows that palette's numbered locations, and makes it the active palette for plotting.
  3. Click the location that holds this tool's paint, and choose Use for Refill.
  4. Click the location that holds water, and choose Use for Prime/Wash. Choose it again for Use for Pre-Refill or Use for Post-Refill if the tool should rinse there too.
  5. Check each stage's settings on the right of the card, described in §8.8.2 Stage settings.
  6. Click SAVE CHANGES.

The preview then shows the paint location filled with the tool's color, and the water location marked as a water dip. The same numbers appear in each stage's row of location boxes.

Clicking a location opens a menu:

The menu a palette location offers, with a check mark on each stage already using it
The menu a palette location offers, with a check mark on each stage already using it

One location can serve several stages, such as a single water well used for Prime/Wash, Pre-Refill, and Post-Refill. A stage can also use several locations, which the brush visits in the order they are listed, dipping the stage's repeat count at each.

Each stage's row of numbered boxes offers the same changes by number. Click a box and choose Edit to type a different location number, or Delete to remove it, and click + to add a location by number. The range of valid numbers is shown as you type.

The preview colors each location by how the tools in the current toolset use it:

Hover over a location to see which tools use it and for what. Changes appear in the preview after you click SAVE CHANGES.

Note

With a toolset selected rather than a single tool, the preview shows the combined locations of every tool in the toolset, and locations cannot be changed. Select an individual tool to change where it dips. Changes to a preset tool last until you quit Studio; to keep them, use Copy to to make an editable copy first. See §14.8 Copying and moving tools.

8.8.2 Stage settings #

Each stage on the right of the Tool Macro Setup section reads as a sentence, such as "Dip 2 times in location 4 at Water depth, after tool change, and before other actions." Its parts are:

The Balance Pigment (Scrape at Basin) tool, whose stages dip at several locations
The Balance Pigment (Scrape at Basin) tool, whose stages dip at several locations

The water and paint dip depths are set in the tool's Tool Settings section, so changing them there changes every stage that uses them. See §15.1.5 Brush heights for the ArtFrame, and §15.4.2 Brush heights for the WaterColorBot.

Hold Position on Tool Change, at the top of the card, is the same setting as in Tool Settings.

Stage settings, like locations, are saved with SAVE CHANGES.

8.9 Palette selection #

Studio uses one active palette at a time. The palette menu in Tool Macro Setup, the Palette menu on the PREPARE tab, and the palette you select on the Tool Library's PALETTES tab all set that same palette, so choosing one in any place changes it in the others. See §14.9 The PALETTES tab.

A tool stores its locations separately for each palette. The same tool can refill at location 3 on the 12 Pan / Crayola palette (WaterColorBot's default) and at location 5 on the 16 Pan palette, and switching palettes switches between them. A tool's repeat counts, refill cycles, and depths are the same for every palette.

When preparing a job, only one toolset and one palette layout are used for that job.

8.10 Testing and calibrating painting tools #

Run a simple and short test pattern first.

Favor strokes long enough to pull the brush across the paper, not only tiny dabs, unless dabs are the intended effect.

Observe how paint loads, how strokes evolve, and how refills affect consistency.

Tune in this order: brush compression first, then refill rhythm, then macro counts and intervals. Each step changes how much paint reaches the paper, so settling the mechanical one first keeps you from compensating for it in software.

Brush compression is how far the bristles press against the paper. On the WaterColorBot, it is set only by where the brush sits in its holder: if strokes are overly wet, spread too much, or buckle the paper, raise the brush slightly in its holder; if they skip or look dry, lower it. On the ArtFrame, you set it when you install the brush, by how far you lower it onto the Pen Height Setup Tool: a light touch on the tool gives a light touch on the paper, and bristles that bend against the tool bend the same way against the surface, with a little extra from the brush presets. Once you find a position you like, note how the bristles flex at that height, or mark the brush shaft, so you can set it up the same way again.

Adjust Travel/Park Height if the brush drags or lifts more than necessary during travel moves. A higher travel height reduces the risk of dragging a wet brush across the paper; it affects how clean the painting is, not the look of individual strokes.

Watch the paper. Buckling, pooling, bleeding, dry strokes, and uneven pigment are all useful feedback:

Before starting, wet each paint pan with a few drops of water so that the first strokes load properly.

Run the same test twice before changing anything. Minor variation between runs is expected; a large difference usually means something in the setup changed, such as the brush position or the water level.

Save known good configurations as new tools or toolsets.

Tip

Run the same SVG with several tool variations and compare results side by side. This is one of the fastest ways to understand how small changes affect the final painting.

9. The Image Processor #

The Bantam Tools Image Processor™ turns a photograph or other raster image into an SVG file of brush strokes that Bantam Tools Studio™ can paint or plot. This chapter walks through converting a first image, then provides reference documentation for each part of the Image Processor window. You need it if you want to start from a picture rather than from vector artwork.

9.1 What the Image Processor does #

A raster image (a PNG or JPEG file, for example) is a grid of colored pixels. A machine cannot follow pixels, so Studio cannot plot one directly. The Image Processor bridges that gap: it reduces the image to a small set of paint or pen colors, then lays down strokes of a chosen brush width to reproduce it, and saves those strokes as an SVG file with one layer per color.

It offers three ways of building the picture from strokes, called render modes:

Each is described in §9.5 Render modes.

The output is meant for painting on WaterColorBot™ or ArtFrame™ with brushes, or for plotting with broad markers: it builds the picture by filling areas with strokes rather than by tracing outlines. Its optional Detail Trace layer adds outlines on top; see §9.7 Detail Trace.

The Image Processor works at a resolution tied to the paper size, resizing the image to about one pixel per millimeter of the printable area whatever the resolution of the original. Larger paper gives a proportionally larger grid. Images with clear shapes and good contrast reproduce best.

9.2 Opening the Image Processor #

The Image Processor opens in its own window, separate from the main Studio window. There are four ways to open it:

If the Image Processor is already open, the new image replaces the one it was showing.

The Image Processor accepts PNG, JPEG (.jpg or .jpeg), BMP, and GIF files, one at a time. A GIF opens as a still image. Files larger than 50 MB are refused, and images larger than 4,096 pixels on a side are scaled down as they load, which loses nothing given the processing resolution described above.

9.3 Converting your first image #

The quickest route from a photo to a painting uses the default settings and changes only what matters most: the paint colors and the brush.

  1. Open your image in the Image Processor, as described above. It processes the image at once, using Paint Stripes, a 4 mm brush, and the Crayola palette, and shows the result under SVG Preview.
  2. Choose a render mode from the menu below Basic and Advanced. Paint Shades suits most photographs.
  3. Expand Paper & Layout and set Paper to the paper you will paint on. The Image Processor matched the orientation to the image when it loaded.
  4. Expand Color Processing and set Palette to the paints you have.
  5. Expand Tool Configuration and set Stroke Width to the width of the mark your brush makes.
  6. Look over the preview. Each change reprocesses the image after a short pause, so you can compare settings as you go.
  7. Click Save & Load in Studio, and choose a name and folder for the SVG file. Studio closes the Image Processor and opens the SVG on the PREPARE tab.

The artwork is now an ordinary SVG job, with one color for each paint in the Tool Assignments list. Choose a painting toolset, assign tools, and preview the motion as for any other job; §9.12 Painting Image Processor artwork covers the points particular to Image Processor output.

The Image Processor, with the parrot sample processed in Paint Shades
The Image Processor, with the parrot sample processed in Paint Shades

9.4 The Image Processor window #

The window has four areas:

9.4.1 Header bar #

Turn off Auto Refresh when each run takes long enough to interrupt your work, such as with a large paper size and a fine brush. The preview then keeps showing the last result, and a banner reads "Settings changed, process image to see result" until you click Process Image.

9.4.2 Basic and Advanced #

The Basic and Advanced switch at the top of the settings panel controls how much of the panel is shown. (Default: Basic)

Advanced adds two things: the color and brightness sliders in Image Adjustments, and the Detail Trace (Pen Layer) section. Every other setting is the same in both views.

The switch changes what is shown, not what is used. Adjustments or a Detail Trace layer set up in Advanced stay in effect after you switch back to Basic.

9.4.3 Settings sections #

The settings below the render mode menu are grouped into sections that start collapsed. Click a section's title to expand or collapse it. A collapsed section shows a one-line summary of its settings beside the title, such as "Letter, 10.0 mm margin," so you can check them without expanding anything.

The sections are, in order:

The thumbnail at the top of the panel shows the source image with its rotation, flips, and color adjustments applied, and the file name below it.

9.4.4 SVG Preview #

The SVG Preview draws the processed strokes on a sheet the shape of the selected paper, at the colors and opacity they carry in the SVG file. It is a picture of the artwork, not a motion preview: it does not show plotting order or travel, which you review in Studio after loading the file.

If you change the paper size or orientation while Auto Refresh is off, the sheet turns gray and reads Paper Size Changed, since the previous result no longer fits it. Click Process Image to fill the new sheet.

9.4.5 Processing time #

While the image is processing, a Processing dialog shows the current stage and a progress bar, with a Cancel button.

Before a run that it expects to take more than about 30 seconds, the Image Processor asks first, with a Long Processing Time dialog. It gives the estimated time, a complexity rating, and the number of grid cells to process. Click Proceed to start processing, or Cancel to leave the preview as it was.

The estimate grows with the printable area and shrinks with the square of the brush width, and Paint Shades takes about three times as long as Paint Stripes. For example, 18" × 24" (Arch C) paper with 10 mm margins in Paint Shades is estimated at 57 seconds with a 2 mm brush, but 14 seconds with a 4 mm brush, which does not ask at all. To shorten a run, use a wider brush or a smaller paper size.

9.5 Render modes #

The render mode menu, below Basic and Advanced, sets how the Image Processor builds the picture from strokes. The choice changes the look of the result more than any other setting.

The same photograph in Paint Stripes, Paint Shapes, and Paint Shades, left to right
The same photograph in Paint Stripes, Paint Shapes, and Paint Shades, left to right

The settings particular to each mode are in the Mode Options section.

9.5.1 Paint Stripes #

Paint Stripes covers the image with straight, parallel strokes, each one brush width wide, laid side by side with no gap. As a stripe crosses the image, it changes color wherever the image does, becoming a separate stroke of the new color.

The result has a woven, graphic look, and it is the fastest mode to process and to paint. It suits bold images, flat brushes, and markers, and it is a good way to see how a palette handles an image before trying the slower modes.

The number of stripes follows from the brush width: a narrower brush gives more stripes. How far neighboring stripes overlap, or how far apart they sit, is set by Stroke Overlap/Spacing; see §9.8 Tool Configuration.

The Mode Options for Paint Stripes are:

Without dithering, each part of the image takes the single nearest palette color, so a smooth gradient, such as a sky, can break into distinct bands. Dithering divides the image into blocks half the brush width across (and at least 3 mm), then assigns palette colors to the blocks so that, seen from a distance, they average out to the colors between. The methods are:

9.5.2 Paint Shapes #

Paint Shapes divides the image into regions of flat color, each matched to a palette color, in the manner of a paint-by-numbers kit. Each region is outlined with a stroke along its edge and filled with concentric strokes that step inward from that edge.

It suits images with large areas of distinct color, such as illustrations, posters, and simple photographs, and it produces the cleanest edges of the three modes. Gradients become visible steps.

The Mode Options for Paint Shapes are:

9.5.3 Paint Shades #

Paint Shades paints with loose strokes that follow the direction of edges and forms in the image, like the strokes of a painter working quickly. Rather than choosing a single palette color for each area, it layers translucent strokes of different paints to build intermediate shades.

It suits photographs, portraits, and landscapes, and gives the most painterly result. It is also the slowest mode to process, and because its strokes overlap freely, the painting depends more on how the paint behaves on the paper than in the other modes.

How translucent each stroke is comes from Line opacity, in Color Processing; see §9.10 Color Processing.

The Mode Options for Paint Shades are:

Paint Shades can also paint with several brushes of different widths, set in Tool Configuration; see §9.8 Tool Configuration.

9.6 Image Adjustments #

Image Adjustments changes the source image before it is processed. Nothing here alters the image file on disk. Its controls appear once an image is loaded.

In Advanced view, four sliders adjust the image's color:

Adjustments are a good way to steer the palette. Raising Saturation helps a muted photograph use more of a bright palette, and raising Brightness leaves more of the paper unpainted when white areas are skipped.

9.7 Detail Trace #

Detail Trace (Pen Layer) adds a layer of thin black lines that trace edges and details in the image, drawn after all of the paint. It is meant for a pen or fine marker, run once the paint has dried, to restore the definition that broad brush strokes lose. The section appears in Advanced view, and it works with all three render modes.

The two strategies are:

Detail Trace changes reprocess only the trace layer, reusing the paint strokes already made, so they update faster than other settings.

9.7.1 Advanced Detail Trace settings #

The Advanced group, inside the section, holds the settings of the edge-finding methods. The defaults suit most images; reach for these when the trace picks up too much texture or misses edges you want.

For both strategies:

For Organic:

For Geometric:

9.8 Tool Configuration #

Tool Configuration sets the size of the brush the strokes are made for.

A little overlap helps hide the paper between strokes, since a brush rarely lays down an edge as crisp as the preview shows. Show Grid draws cells at the resulting stroke spacing, and the processing time estimate grows as the spacing narrows.

9.8.1 Multiple Brush Widths #

In Paint Shades, the Multiple Brush Widths check box lets the image be painted with several brushes, the wider ones covering broad areas and the narrower ones adding detail on top. (Default: off)

When it is selected, the Stroke Width slider is unavailable, and a field below the check box takes the brush widths, in millimeters regardless of the display units, separated by commas: 10, 5, 2. Up to 10 widths from 0.1 to 100 mm are accepted. The widest brush is painted first.

Each brush width becomes its own set of layers in the SVG file, so in Studio you can assign a different brush tool to each. Save also writes one additional SVG file per brush; see §9.11 Saving the artwork.

9.9 Paper & Layout #

Paper & Layout sets the sheet the artwork is made for. The SVG file is exactly this size, and Studio keeps that size when it loads the file, so choose the paper you will actually use.

When an image loads, the Image Processor sets the orientation to match it: landscape for an image wider than it is tall, and portrait otherwise. Change it afterward if you want the other.

Match the margin here to the margin you plan to use in Studio. The Image Processor has no notion of a machine's reach or a palette's position, and a margin that is narrower here than on the PREPARE tab will have its outer strokes cropped there.

9.10 Color Processing #

Color Processing sets the colors the image is reduced to, and how its white areas are treated.

9.10.1 Palette #

The built-in palettes model paint sets by their colors:

With Grayscale or Image Colors selected, a Colors field sets how many colors to use. Image Colors counts white among its colors, so a setting of 8 gives seven colors from the image, plus white.

A palette color that no part of the image is matched to produces no strokes, so the SVG file can hold fewer colors than the palette.

With mixing on, the panel also shows the most strokes that can be layered in one area, which follows from Line opacity.

9.10.2 White areas #

Paper is usually white, so by default the Image Processor paints nothing where the image is white, and lets the paper show through.

Near-white areas of the image, not only pure white, count as white.

9.10.3 Line opacity #

Line opacity models how transparent watercolor is. In the SVG Preview, lower values let overlapping strokes show through each other. In Paint Shades, it also sets how many strokes can be layered to build a shade: at 80%, two strokes at most, and at 30%, four. Lower it for thin, transparent paints; raise it toward 100% for opaque paints and markers, which hide what lies beneath them.

The opacity is recorded in the SVG file, but it describes the look of the result rather than controlling the machine, which paints every stroke with whatever the brush carries.

9.10.4 Custom Palette dialog #

With Custom Palette selected, click Edit Custom Palette to open the Custom Palette dialog. The button shows how many colors the palette holds. A new custom palette starts with eight bright colors, to edit or replace.

The dialog lists the palette's colors, up to 16, each on a row:

Below the list:

Click OK to use the palette.

For paints you own, the most faithful colors come from a painted swatch rather than from the name on the pan: paint a stroke of each color on the paper you will use, photograph or scan the swatches, and enter the hex codes from the image.

9.11 Saving the artwork #

The export bar below the preview saves the processed artwork as an SVG file. Its buttons are available once a result is showing.

Studio rotates the loaded artwork, if needed, to fit the paper, and centers it.

9.11.1 What the SVG file contains #

The SVG file is a sheet the size of the paper, in millimeters, with the artwork inside the margins. Its strokes are grouped into layers, one for each combination of color and stroke width, named for their order, color, and width, such as 3 - #1F75FE 4.0mm.

With Lightest to darkest selected, the layers are ordered from the lightest color to the darkest. This is usually the right order to paint in, since pigment carried over on the brush then darkens later colors rather than tinting light ones. The layer numbers in the names do not follow this order. With it cleared, the layers are ordered darkest to lightest.

Water strokes, from water wash or water blending, are on layers of their own, in pale blue colors that differ slightly from one layer to the next. Each sits beside the color it blends: before the paint, or after it, as the mode's settings direct.

A Detail Trace layer, named Detail Trace, is always last, after every paint layer, whichever order is selected.

With Multiple Brush Widths, Save writes the combined file under the name you chose, plus one file per brush with its width added to the name, such as parrot_5.0mm.svg. The per-brush files hold that brush's strokes alone, without the Detail Trace layer. Save & Load in Studio writes the combined file only.

The Image Processor does not save its settings with the SVG file or anywhere else. To return to a result later, keep the SVG file, and note the settings that produced it.

9.12 Painting Image Processor artwork #

Artwork from the Image Processor is an ordinary SVG file once it is saved, and it is prepared on the PREPARE tab like any other; see §12. The PREPARE tab and §8. Painting. A few points are particular to it.

The stroke count can be large. A Paint Shades painting on a large sheet may take many hours of brush travel and refills, so check the estimated time on the Setup Sheet before you commit to it; see §11.5 Setup Sheet. For a first attempt, a small paper size and a wide brush give a quick, inexpensive test of the palette and the settings.

10. Sending files to your machine #

Whatever you prepare in Bantam Tools Studio™ leaves the computer as a G-Code file: a plain text file holding the moves the machine will make. There are three ways to get that file onto the machine, and they differ only in how the file travels. Once it arrives, the machine runs it the same way in all three cases.

This chapter compares the three, then covers each one in turn, and ends with how to put your machine on a network. For every control on the MACHINE tab that the USB and WiFi routes use, see §16. The MACHINE tab.

10.1 Which route to use #

We recommend learning the microSD card route first. It gets your machine running on day one with nothing to configure, so you can confirm the machine itself is set up and working before adding a network or a cable to the picture. A card reader and a card are the whole dependency. When a file is on the card, the file is on the machine.

WiFi can be the most convenient route once your machine is settled in place. The machine joins a 2.4 GHz network, Studio finds it there, and files travel with no USB cable and no card handling — the machine can live across the room, and several people on the network can send to it.

USB sits between the two. It depends on nothing but a cable, the same as the card, and it lets Studio upload, start, pause, and cancel a job without your leaving the computer. The machine has to sit within a cable's length of the computer, and the cable has to stay put while the job runs.

Each route at a glance:

Which route suits you depends on where the machine sits and what your network allows. Most owners end up using more than one — a card for a machine set up away from the desk, USB when tuning a job and re-running it repeatedly. You can change routes at any time; nothing about a job is specific to how it traveled.

10.2 Sending files on a microSD card #

The machine reads G-Code files from a microSD card and runs them with no computer attached. The card that shipped with the machine already holds the welcome file, and it is also where your own work goes.

  1. In Studio, generate and save the G-Code file for your job.
  2. Turn the machine off, then remove the card. (You can also swap the card with the machine on, once it is idle: no file running, and no upload or file change under way from Studio.)
  3. Put the card in your computer's card reader and copy the file onto it.
  4. Eject the card from your computer and put it back in the machine.
  5. At the machine, open the file browser, scroll to the file, and press the control knob to start it.

The machine moves to its loading position and waits for you to load the tool and the media.

Browsing the card at the machine — opening folders, running a folder of files one after another, Run Again, and the check marks that mark completed files — is covered in the user guide for your machine, which documents every menu on the machine itself.

10.2.1 Keeping files in folders #

A folder groups related files so the machine can run them in sequence: a batch of individual letters, or a Stack produced by Data Merge. Copy the whole folder onto the card and the machine treats it as a set, offering to continue to the next file as each one finishes.

10.3 About microSD cards #

The machine reads microSD cards formatted with the FAT32 file system, sometimes called MS-DOS (FAT). The card that ships with the machine is ready to use as it comes, and so are new cards of 32 GB and smaller; a larger card works once you reformat it as FAT32. Formatting erases everything on the card, so move anything you want to keep off it first.

Buy microSD cards from a seller you trust. Counterfeit cards, sold under the names of reputable brands, hold far less than their labels say; they appear to work normally, then lose or corrupt files as they fill. Reformatting clears ordinary file errors, but a counterfeit card fails again as it fills, so replace a card that loses or corrupts files.

Keep the card with the machine's accessories when it is not in the machine. Avoid bending it, touching its metal contacts, or leaving it loose on a work surface.

10.4 Sending files over USB #

A USB cable connects the machine directly to your computer, and Studio then uploads files and drives the machine without anything in between.

The Bantam Tools ArtFrame™, Bantam Tools HandWriter®, Bantam Tools WaterColorBot™, and Bantam Tools EggBot™ all use a USB-B connection — the squarish connector sometimes called printer-style. Use a USB cable with USB-B at the machine and USB-A at the computer, or a USB-B to USB-C cable if your computer has only USB-C ports.

To send a job over USB, connect the cable at both ends, open the MACHINE tab in Studio, and click Connect. Studio favors USB automatically when your machine is available on it. Once the connection row reads USB Serial, upload the file with Upload File and start it with Begin Selected, or send the job straight from the Setup Sheet after processing it. The full set of controls is in §16. The MACHINE tab.

Files uploaded over USB land on the machine's microSD card, exactly as if you had copied them there yourself, so they stay on the machine after the job and after a power cycle.

10.5 Sending files over WiFi #

To send over WiFi, the machine has to be on the same network as your computer; see §10.6 Putting your machine on a network. After that, connect from the MACHINE tab with Scan for Plotters, or with Enter IP if the scan finds nothing, and upload as you would over USB.

The machine joins 2.4 GHz networks. Most routers broadcast 2.4 GHz and 5 GHz under a single name, and the machine uses the band it supports; where a router names the two separately, give the machine the 2.4 GHz name.

Studio checks every WiFi upload against the size it sent. If the machine's microSD card is full, Studio reports that there is not enough free space for the file: delete files from the card and try again. If the file arrives incomplete, the machine rejects it and Studio says so; send the file again.

Some networks cannot carry your machine at all. The machine needs a network with a password; networks without one, or that ask for a user name, are not supported. A network that asks you to sign in, whether on a browser page or with your own user name and password, has no way to ask a machine for either. Many networks at businesses, academic institutions, and secure facilities are also set up to keep devices like these off them. On those networks, send files over a USB cable or on the microSD card.

10.6 Putting your machine on a network #

A machine joins a network once it knows the network's name and password. Studio's Set Up Your Plotter dialog collects both and delivers them to the machine, either over a USB cable or in a file on the machine's microSD card.

  1. Open the MACHINE tab, click Connect, and choose Setup New Plotter.
  2. Enter a Plotter Name you will recognize later, especially if you own more than one machine.
  3. Choose how to send the WiFi settings: Over a USB cable or With a file on a microSD card. Over USB, connect the machine with a USB cable; NEXT appears once Studio finds it.
  4. Enter the WiFi Name (SSID) and WiFi Password for the network the machine should join, and continue.
  5. Over USB, Studio writes the settings to the machine directly. Click Reboot Plotter to restart the machine on your network.
  6. With a microSD card, click Save File and save the setup file, then copy it onto the machine's microSD card as wifi_setup.txt. Put the card back, restart the machine, and click Plotter Rebooted.

If the machine's firmware is too old to receive WiFi settings over USB, the first page reads Firmware update required. Update the firmware, then reconnect the machine.

The first page of the Set Up Your Plotter dialog, with With a file on a microSD card chosen
The first page of the Set Up Your Plotter dialog, with With a file on a microSD card chosen

The card route's last step: Save File, then Plotter Rebooted once the machine has restarted
The card route's last step: Save File, then Plotter Rebooted once the machine has restarted

Studio then looks for the machine on your network, and the machine appears the next time you Scan for Plotters. If it does not, choose Enter IP address manually and enter the machine's address.

The machine shows its own address on its display, under WiFi Status. Studio also shows it beside each machine in the Plotters on network list, and beside the name of a machine it is already connected to over WiFi.

WiFi Status on the machine's display, showing its IP address.
WiFi Status on the machine's display, showing its IP address.

Note

Network settings live on the machine, not in Studio, and they survive a power cycle. When the network's name or password changes, run setup again — the machine has no way to learn the new password on its own.

For a description of every control in the dialog, see §16.4 Setting up a new plotter.

11. Exporting output #

Use this chapter when you need a file other than G-Code for a machine, or want to know what a Setup Sheet or a project file records.

Every export in Bantam Tools Studio™ starts from the PROCESS AND SAVE button in the upper-right corner of the window. Click the button itself to run its default action, or open its chevron menu to choose another format. This chapter covers everything that button and its menu produce — G-Code, SVG, and Plob, plus Save Project and Save Project As — along with the Setup Sheet that follows a G-Code export and the Split by Toolset option that can turn one job into many files.

11.1 Process and Save G-Code #

Process and Save G-Code is the default action of the PROCESS AND SAVE button. Click the button, or choose Process and Save G-Code from its chevron menu, and Studio processes the current job and saves a machine-ready .gcode file.

This is the output path you will use most, and the right choice when you want to copy a file to a microSD card, upload it to a connected machine, or keep a machine-ready copy for later.

The PROCESS AND SAVE chevron menu
The PROCESS AND SAVE chevron menu

Processing uses the current machine selection, the Setup and Options panels, your tool assignments, and the paths shown in the Preview, so the file reflects the job exactly as you have arranged it — see §12. The PREPARE tab for how those are set up.

The same G-Code output is available from the File menu, as Save G-Code File (⌘↩ / Ctrl+Enter), and you can generate and upload in one step with Generate G-Code and Upload — see §16. The MACHINE tab.

Once the file is written, Studio opens a Setup Sheet summarizing the job; see §11.5 Setup Sheet, below.

11.2 Save as SVG #

Choose Save as SVG from the PROCESS AND SAVE chevron menu to save the processed artwork as an SVG file rather than as G-Code.

The file carries the job as you arranged, scaled, and processed it, which makes it the format to reach for when the artwork is going back into a drawing program, or to someone who has no use for a machine-ready file.

Save as SVG is available whenever Studio can process the job.

11.3 Plob #

Plob, short for "Plot Object," is a highly specialized kind of SVG file. The processing work is already done inside the file, so Studio can send a Plob straight to a machine with no further preparation. Use it when you want a file prepared in advance for one specific machine, ready to go with no extra processing step. A Plob is saved as an ordinary SVG file, with _plob before the extension (card_plob.svg), so it opens anywhere an SVG does, such as Inkscape.

Save as Plob appears in the PROCESS AND SAVE chevron menu only after you turn on Enable Plob output in Settings. See §17.1 Program options.

Because a Plob is prepared for a particular machine, two settings in Settings' Plob group shape the export:

11.4 Project files #

A project file (.btsp) bundles a whole session into one file: the documents you have open, your tool assignments, the selected palette and toolset, and the generation settings that produced your output. Opening a project restores all of it, so you can pick a job back up weeks later, or hand it to a colleague and have it come out the same.

Save a project from the PROCESS AND SAVE chevron menu or the File menu, and open one from the File menu:

11.4.1 Opening a project #

If the project's settings match your current ones, it opens without asking. If they differ, an Open Project dialog lists each setting that differs, with your value beside the project's value, and offers three choices:

Open Project dialog listing the settings that differ
Open Project dialog listing the settings that differ

If the project was saved for a different machine than the one you have selected, a Machine Type Mismatch dialog appears first:

Studio opens projects saved by earlier versions. Each project also records the file format it was saved in, and a version of Studio older than that format does not open it: it reports "This project requires Bantam Tools Studio X or later", naming the version that saved the project. See §19.8 Project file problems.

When some of a project's documents cannot be loaded, the rest open anyway and a Some files failed to load message lists the ones that did not; those appear as placeholders. For other errors when opening a project, see §19.8 Project file problems.

11.4.2 Support info in project files #

Saved project files include a small, redacted diagnostic record. It holds your app and system versions, a list of recent activity, and recent lines from the log, so that Bantam Tools support can diagnose a problem from a project file you send. Passwords, Wi-Fi network names, and your user name are removed before the record is written.

To leave the record out of the projects you save from now on, turn off Include support info in project files; see §17.1 Program options. Turning it off changes nothing in project files you have already saved. About Project Files, on the SETTINGS tab, summarizes the same information.

11.5 Setup Sheet #

After you process a G-Code job, Studio opens a Setup Sheet: an on-screen summary of the job that you can review before you start, and save as a PDF to print or keep with the job. When the job produced more than one output file, the window is titled Batch Setup Sheet and summarizes the whole run.

The Setup Sheet for a single job
The Setup Sheet for a single job

A Batch Setup Sheet for a Data Merge, with one row per output file
A Batch Setup Sheet for a Data Merge, with one row per output file

The Setup Sheet can include:

The total pen down distance and the estimated time are the two figures worth reading every time: together they tell you how long the job will take before you commit to plotting, writing, or painting it.

The lower part of the Setup Sheet: the operations list and the settings behind the job
The lower part of the Setup Sheet: the operations list and the settings behind the job

If Studio finds a problem while generating the job — a move outside the machine's acceptable bounds, say, or a job with almost nothing to draw — the sheet lists it under WARNINGS. Click Copy to copy the warning text, which is the quickest way to paste it into a message to support.

The button at the bottom of the Setup Sheet is a split button. It shows one action, DONE at first, and keeps the rest in its chevron menu. Choosing an action from the menu also makes it the button's action until you quit Studio, so a step you repeat on every job, such as uploading over USB, becomes a single click.

DONE button on the Setup Sheet, with its menu chevron
DONE button on the Setup Sheet, with its menu chevron

The actions are:

  • DONE — closes the Setup Sheet. Nothing is saved, and nothing is lost: the G-Code file was written when the job was processed.
  • SAVE SETUP SHEET — for a single document, saves the sheet on screen as a PDF. The suggested file name matches the G-Code file, with a .pdf extension.
  • SAVE BATCH SETUP SHEET — takes the place of SAVE SETUP SHEET when the job produced more than one file. It saves the batch summary as a PDF: the date, the number of files, the total pen down distance and estimated time, the tools used across the batch, and a table with one row per file. The suggested file name is batch_setup_sheet.pdf, in the G-Code output folder. It does not save a sheet for each individual file.
  • SAVE SETUP SHEET PER FILE — appears only for a batch. Choose a folder, and Studio writes one setup sheet PDF into it for each G-Code file in the batch, named like that file with _setup added: Envelopes_3.gcode gets Envelopes_3_setup.pdf. (As a special case, a Data Merge whose documents flow onto more than one page gets one sheet per document rather than one per page.)
  • OPEN FILE LOCATION — reveals the generated G-Code file, selected in a Finder window on Mac or an Explorer window on Windows.
  • UPLOAD VIA USB, or UPLOAD ALL VIA USB for a batch — uploads the generated file or files to the connected machine over USB. It is always available: if no machine is connected yet, the Queue holds the upload and sends it once a machine comes online over USB.
  • UPLOAD VIA WIFI, or UPLOAD ALL VIA WIFI for a batch — uploads over WiFi. It is available when a machine is reachable over WiFi.
Setup Sheet menu for a single file
Setup Sheet menu for a single file

The two upload actions appear only when Show Machine Control Tab is enabled:

Settings → Machine Control → Show Machine Control Tab

With it disabled, the menu holds the save and open actions alone. For more on connecting and uploading, see §10. Sending files to your machine.

Setup Sheet menu for a batch of files
Setup Sheet menu for a batch of files

11.6 Split by Toolset #

When Split by Toolset is enabled in the PREPARE tab's Options panel, Studio writes a separate G-Code file for each color, layer, or group, alongside the main output file. Reach for it on a multi-tool job when you want manual control over the order of work — running each pen color as its own pass rather than letting Studio interleave tool changes.

The setting applies to the whole job rather than to one page, so with several documents open every page is split and the file count multiplies quickly. See §12.11.3 Split by Toolset for the detail, and §11.7 Output file names, below, for how the split files are named.

11.7 Output file names #

When a job produces one output file, the file takes the name you enter in the save dialog. When it produces several from one source — a Data Merge, or a document flowed across pages — Studio names each file for you: the source document's name, an underscore, and a suffix that tells the files apart. The same rule applies to every batch format, G-Code, SVG, or Plob alike, and the files go into the folder you choose when the batch starts.

Files opened together are the exception: each output keeps its own source file's name, with no suffix, because the names already differ. Two files with the same name, opened from different folders, produce a single output file, and the second replaces the first.

For a Data Merge, which is part of the Bantam Tools Studio Text Add-On, the suffix comes from the Merge File Naming setting:

Settings → Program Options → Merge File Naming

A multipage document adds a page suffix: Letter_p1, Letter_p2. A Data Merge document that flows onto more than one page adds the page suffix after the document suffix: Letter_Alice_p1, Letter_Alice_p2. The document suffix tells documents apart; the page suffix tells the pages of one document apart. A document comes to have pages by way of the Use multiple pages overflow setting, described in §6.7 Multipage layout. Combining that with Data Merge is covered in §7.6 Data Merge with multipage documents.

A Plob's name ends in _plob.svg, after any document or page suffix: card_plob.svg, card_p2_plob.svg.

Split by Toolset uses neither suffix. Studio puts the per-tool files in a folder of their own, created beside the main output file and named for it without the extension, and names each one for the color, layer, or group it holds, numbered in the order it is plotted, written, or painted: 1-Black.gcode, 2-Red.gcode. Where the tool's name differs from the grouping's, it follows after an underscore. In a batch, each document gets its own folder, named for that document's output file.

Note

When a document has no merge fields — a row range used only to set how many copies to produce, for instance — the files are numbered sequentially from 1 whichever naming mode is selected, because there is no row or column value to name them from.

Part III: Reference

12. The PREPARE tab #

This chapter documents every control on the tab: what each one does and when to change it.

The PREPARE tab is where you set up a job before processing, saving, or sending it to a machine. It is the main workspace for choosing the machine, defining the paper or work area, placing the artwork, assigning tools, setting path processing and G-Code behavior, and checking the result in the Preview.

The tab is divided into four areas:

This section is reference material: it describes every control on the tab, in the order the tab presents them, rather than walking a job from start to finish. For one drawing taken from start to finish, see §5. From drawing to G-Code.

The PREPARE tab: SETUP, OPTIONS, the Preview, and PROCESS AND SAVE
The PREPARE tab: SETUP, OPTIONS, the Preview, and PROCESS AND SAVE

Tip

Hover over any setting in Bantam Tools Studio™ to see a short description of what it does.

12.1 Opening files and file actions #

The OPEN FILE button sits in the upper-left corner of the Studio window. Click OPEN FILE and choose the source file you want to prepare.

You can also choose more than one. Select several SVG files in the dialog and Studio opens them together: each becomes a page you step through in the Preview area's page navigator, and one PROCESS AND SAVE writes output for every one of them. A batch is all SVG files or all text files (.txt or .rtf), and an image file opens on its own. Some of the Setup controls then belong to the page in front of you and the rest to the whole job — see §12.2 What belongs to one document and what belongs to all. Opening several text files together is part of the Bantam Tools Studio Text Add-On; see §6. Writing text.

With several files open, the menu adds Reload all files from disk
With several files open, the menu adds Reload all files from disk

The chevron beside OPEN FILE opens a menu of additional file actions. Some items appear only when they apply, as noted below:

  • Reload file from disk: Reloads the currently open file from its saved location, and keeps your tool assignments, plotting order, placement, and handwriting variation. Colors and layers that are new in the file get tools automatically. Use this after editing the source file in another program.
  • Reload all files from disk: Rereads every file at once when you have opened several. The item appears only then — not for a Data Merge batch, whose documents come from one file — and with a single file open, Reload file from disk is the one to use.
  • Show file location on disk: Opens the folder containing the current file.
  • Rescale Illustrator SVG: Some Adobe Illustrator files do not correctly encode the document size, and open in Studio at three-quarters of their intended size. If that happens, choose this command to correct it; in a multipage document it applies to every page. A saved project keeps the correction, but opening the file again on its own does not. To have Studio correct such files automatically as they open, see §17.1 Program options.
  • Show samples and generators: Opens Studio's included samples and generator resources.
  • Open from Clipboard: Creates a new job from supported clipboard content, such as SVG, PNG, text, or RTF, depending on what is available.
OPEN FILE menu with Rescale Illustrator SVG available
OPEN FILE menu with Rescale Illustrator SVG available

Tip

If you are iterating between Studio and another design program, Reload file from disk updates the Preview without your reopening the file each time.

12.1.1 File types Studio opens #

OPEN FILE opens these kinds of file:

Text documents and CSV data are part of the Bantam Tools Studio Text Add-On; without it, the OPEN FILE dialog leaves them out of its list. See §13.5 About the Text Add-On.

One open takes one kind of file: SVG files, text files, one CSV file, one image, or one project. Choosing a mix brings up a Mixed File Types message, and nothing opens.

Content copied from another program, such as SVG artwork, an image, or text (including formatted text copied from a web page or Google Docs), opens with Open from Clipboard instead. See §3.6.2 Pasting from the clipboard.

12.1.2 When files have different sizes #

The files you open together need not share a size. When they do not, Studio fits each one to the current paper and margins on its own and centers it there, so that every page starts somewhere predictable rather than wherever its own coordinates happen to put it. Rotation returns to 0° for each file as part of that fit.

A Files of Different Sizes Detected dialog tells you this has happened. It appears once for the whole batch, and dismissing it with OK is all it asks of you. The fit is a starting point, not a lock: adjust the scale, offsets, or rotation of any page afterward and Studio remembers the change for that file alone. See §12.2 What belongs to one document and what belongs to all.

The Files of Different Sizes Detected dialog
The Files of Different Sizes Detected dialog

Select Don't show this again in the dialog to stop it appearing on later opens.

12.2 What belongs to one document and what belongs to all #

You can open several documents at once, and Studio shows them as pages you step through in the Preview. When you do, some Setup controls belong to the page you are looking at and the rest belong to the whole job. The division is fixed; it does not change as you switch pages.

The page navigator steps between open documents
The page navigator steps between open documents

These belong to this page alone, and every open document keeps its own:

These are shared, and changing one changes it for every open document at once:

Switching pages therefore changes what Artwork Settings and Tool Assignments show you, and leaves Paper Settings, the margins, and the toolset exactly as they were.

Two commands, both called Apply to All, copy settings across every page: §12.6 Applying positioning to every document copies placement, and §12.9 Applying tool assignments to every document copies tool assignments.

12.3 Machine selection #

The Machine selection drop-down menu, at the top of the SETUP sub-tab, sets the machine target for the current job. The choice affects the available work area, the default settings, machine-specific behavior, and the way Studio generates motion, so make it before you set up the rest of the job.

Select the machine you plan to use from the menu.

The Machine selection menu
The Machine selection menu

Studio supports the Bantam Tools ArtFrame™, Bantam Tools EggBot™, Bantam Tools WaterColorBot™, and Bantam Tools HandWriter®. The selection matters because each of these uses a different physical setup: ArtFrame draws across a flat work area, EggBot maps artwork onto a rotating object, WaterColorBot adds painting workflows with a palette, and HandWriter writes on sheets of paper with real pens.

When you change the machine, these settings return to that machine's defaults: the toolset, the margins, the pen parking height source, the grouping-by-color setting, and the Z heights, feed rates, and accelerations. The paper size menu lists only the sizes the machine can take; your paper size is kept if it fits, and replaced if it does not. Your artwork and its scale and position are untouched.

If you are generating G-Code for a third-party or custom machine, adjust the machine settings in:

Settings → Machine Options

12.4 Paper settings #

The Paper Settings section (Media Settings on EggBot) defines the work area for the job. There is one work area, shared by every open document; see §12.2 What belongs to one document and what belongs to all.

Depending on the selected machine, this may represent a sheet of paper, a flat work area, or another machine-specific drawing area.

The controls are:

The PAPER SETTINGS section
The PAPER SETTINGS section

Standard Sizes lists only sizes the machine can take
Standard Sizes lists only sizes the machine can take

Use Document Size reads the size of the document on the page you are viewing, but the paper size it produces is the shared one, so that page's size becomes the paper size for every open document. It also returns the scale to 100% and the artwork offsets to zero for that page alone; the other pages keep the scale and offsets they had.

X Offset and Y Offset move the paper, and everything drawn on it, relative to the machine. A larger X Offset moves the paper to the right in the Preview, and a larger Y Offset moves it up; the plotted output moves by the same distance on the machine. Neither value can be negative. Like the paper size, the paper offsets are shared by every open document.

The paper offsets do not move artwork on the paper. For that, use the Offsets fields in Artwork Settings, which belong to each page separately and can be negative; see §12.5 Artwork settings.

Most machines start both paper offsets at zero. WaterColorBot starts X Offset at 63 mm. On ArtFrame with a brush toolset and a palette selected, Studio sets X Offset from the palette's width and position, and updates it when you change the palette. Once you enter an X Offset or Y Offset value yourself, Studio stops adjusting it until you select a different machine or restart Studio.

The width, height, and offset fields accept arithmetic and unit suffixes, such as 8 1/2 or 6 in + 3 mm. See §12.5 Artwork settings, under Entering dimensions.

Tip

Units can be selected on the SETTINGS tab, but you can also press ⌘U (Ctrl+U on Windows) to switch between millimeters and inches at any time.

12.5 Artwork settings #

The Artwork Settings section controls how Studio interprets, scales, and positions the loaded artwork.

The ARTWORK SETTINGS section for an SVG document
The ARTWORK SETTINGS section for an SVG document

12.5.1 Content bounds and document bounds #

When Content Bounds is selected, Studio calculates the edges of the artwork from the objects in the file. Extra empty space in the document canvas or viewBox is ignored. (Default)

When Document Bounds is selected, Studio uses the original canvas or viewBox dimensions to position and scale the content.

This choice affects fitting, centering, scaling, and offsets.

Note

With a text document open, this control is the Text overflow menu instead. A text document has no artwork whose edges could be measured, so the bounds choice does not apply and the overflow menu takes the control's place. Scale goes read-only at the same time, reporting the scale the margins produced rather than accepting one you type. See §6.6 Font size, spacing, and overflow.

With a text document, Text overflow replaces the bounds choice
With a text document, Text overflow replaces the bounds choice

12.5.2 Fit to Margins #

Click FIT TO MARGINS to scale the document or its contents to fit inside the paper size and margins.

The command changes the scale and, depending on your settings, the offsets. It does not change the paper size or the margins themselves.

12.5.3 Setting an exact size #

An SVG document carries a page size of its own along with its contents, and Studio scales that drawing onto your paper. Scale works in percent, so an exact width or height comes from setting up the space the artwork fills, or from a ratio. There are several ways, and the one to use depends on what you start with:

Whichever method you use, the bounds choice decides what is measured: Content Bounds sizes the drawn objects, and Document Bounds sizes the canvas. See §12.5.1 Content bounds and document bounds.

Note

A text document works differently, because it has no page size of its own. Studio lays the text out between the margins. Its size comes from the font size, the spacing, and the Text overflow setting, which can scale the text to fit. The methods above apply only to SVG documents. See §6.6 Font size, spacing, and overflow.

12.5.4 Center #

Click CENTER to center the content inside the margins.

CENTER is a split button. Its chevron opens a menu with two choices:

Studio remembers the choice and uses it when it re-centers artwork for you, such as after you change the paper size. Clicking the CENTER button itself switches back to centering within the margins.

The CENTER menu
The CENTER menu

Tip

Double-click the artwork in the Preview area to center it and fit it to the margins in one step.

12.5.5 Scale #

The Scale control displays the scaling factor applied to the artwork as a percentage. For an SVG document you can enter a value to override the calculated or default scale. For a text document the field is read-only: it reports the scale Studio applied to fit the text to the margins.

To set an exact width or height instead of a percentage, see §12.5.3 Setting an exact size.

12.5.6 Offsets #

The X Offset and Y Offset controls shift the artwork horizontally and vertically. You can move artwork by dragging it in the Preview area or by entering values directly.

12.5.7 Rotation #

The two rotation buttons, at the right end of the first row of ARTWORK SETTINGS after CENTER, rotate artwork counterclockwise or clockwise by 90°.

12.5.8 Margins #

Margins define areas at the edges of the paper or work area where nothing is drawn. Artwork outside the margins is shown in red and is cropped when the job is processed.

You can enter margin values or drag margins in the Preview area. Drag a corner of the margin outline to move the two margins that meet there at once; corners can't be dragged while the margins are linked. Margins are shared in the same way paper size is: one set of four values, applied to every open document.

On HandWriter the default margins are not the same on all four sides: about 20 mm at the left, 18 mm at the right, 6 mm at the top, and 28 mm at the bottom, the space the rollers need to grip the sheet. The defaults are a good starting point; the side and top margins can go as narrow as 3 mm.

Reset, to the right of the margin fields, returns all four margins to the defaults for the selected machine. It does not change the paper size, the scale, or the artwork offsets.

The chain-link button between the margin fields and Reset links the four margins. Linking sets all four to the largest of them, and from then on, changing one margin changes all four. The chain is whole while the margins are linked and broken while they are not; click it again to unlink them.

12.5.10 Entering dimensions #

Every dimension field in Artwork Settings and Paper Settings, and the palette offsets in Tool Settings, accepts arithmetic. Type an expression and press Return or Enter, or click elsewhere, and Studio replaces it with the result. Only the result is kept.

Length fields accept mm, cm, in, ft, and pt. Percent fields, such as Scale, accept %, and a bare number is read as a percent, so 4/3 means 1.33% rather than 133%; write (4/3) * 100% for a ratio. On the EggBot, the only machine that measures in degrees, the fields accept ° and deg only.

Put a space before a unit, and it applies to everything before it: 10 / 2 mm is 5 mm, and 1/8 in is an eighth of an inch.

The Up and Down arrow keys step the value by 1 mm or 1/16 in, and by 10 mm or 1 in with Shift held. The first press lands on a round value. Escape abandons an edit and restores the previous value.

A rejected entry outlines the field in tangerine and keeps what you typed so that you can correct it. Hover over the field, or leave the cursor in it, to read the reason, for example "Value is out of range."

For the accepted units and worked examples, see §18.2 Dimension entry reference.

12.5.11 Undoing layout changes #

Undo (⌘Z / Ctrl+Z) and Redo (⇧⌘Z / Ctrl+Shift+Z or Ctrl+Y) step back and forth through layout changes in the Preview. They are also the first two items in the Edit menu, which names the step each will reverse, such as Undo Fit and Center. Each of these is one step:

Each page keeps its own history of up to 50 steps. Paper and margin changes apply to every page, and Undo reverses whichever change came last. While a field still holds your typing, ⌘Z / Ctrl+Z undoes the typing; after Return or Enter, it undoes the layout change. Deleting a tool or toolset, and other changes outside the layout, cannot be undone.

The history clears when you open a document or project, apply a profile, change machine, or use Apply to All for positioning (see §12.6 Applying positioning to every document) or Reset All in SETTINGS.

12.6 Applying positioning to every document #

Scale, offsets, and rotation belong to the page you are looking at, so setting them once does not set them everywhere. Apply to All, at the right of the ARTWORK SETTINGS header, is how you make one page's placement the placement for all of them. The button appears only while more than one document is open.

Click Apply to All to copy this page's scale, X offset, Y offset, and rotation onto every other open document, replacing the values those pages had. This cannot be undone, and it clears the undo history. Tool assignments and plotting order are left alone.

Apply to All appears when several documents are open
Apply to All appears when several documents are open

The confirmation before positioning is copied
The confirmation before positioning is copied

One scale and one pair of offsets suit pages of the same size. On a page of a different size, the copied placement can carry artwork past the margins, where the Preview draws it in red and processing crops it.

12.7 Toolset settings #

The Toolset Settings section, lower in the SETUP sub-tab, determines which group of tools is available for the job.

A toolset is a saved collection of tools and their settings. Every job draws its tools from the toolset selected here, so a job that uses several pens or brushes needs a toolset that holds all of them; see §14. The Tool Library.

The TOOLSET SETTINGS section with a brush toolset and a palette
The TOOLSET SETTINGS section with a brush toolset and a palette

12.8 Tool assignments #

The Tool Assignments section shows the colors, layers, or groups Studio detected in the page shown in the Preview and lets you assign a tool to each one.

The Sort Strokes by menu offers:

Once sorted, each detected color, layer, or group can be assigned a tool from the selected toolset.

A layer whose name begins with % is a documentation layer, and Studio leaves it out of the file it works with: its contents are never read, so the layer is not listed here, takes no tool, and is not drawn. That is the place to put a safe area box, fold lines, crop guides, or notes to yourself, which you want to see in your editor and never want on the page. It applies however you are sorting — a documentation layer is dropped before Studio looks for colors or groups, so nothing inside one appears under any sorting method. Setting a template up this way is covered in §20. Appendix: SVG templates in Inkscape.

When a file has more than 100 colors, layers, or groups of the kind you are sorting by, a Large Number of Groupings Detected dialog asks how many to load:

When several files are opened together, Studio limits each one to 100 without asking.

You can assign tools with the drop-down menus, or use AUTO-ASSIGN TOOLS when it is available. Each drop-down menu also offers None; skip this task, which leaves that color, layer, or group out of the plot.

Click the name of a row to hide it. The name is struck through, its strokes disappear from the Preview, and its tool changes to None; skip this task. Click the name again to show it and bring back the tool it had.

A row set to None; skip this task or hidden stays that way when you reload the file, change toolsets, or save and reopen a project. Assigning a tool to the row brings it back, and AUTO-ASSIGN TOOLS brings back every row.

The TOOL ASSIGNMENTS list, with one row hidden
The TOOL ASSIGNMENTS list, with one row hidden

Once a row has a tool, the gear button at the end of the row opens a Tool Options menu:

  • Assign this tool to all — assigns the row's tool to every color, layer, or group in the list.
  • View/Edit Tool — opens the tool in the Tool Library.
  • View/Edit Toolset — opens the tool's toolset in the Tool Library.

For a tool that uses painting macros, the menu also lists Macro Locations, the palette locations that tool uses for Prime/Wash, Pre-Refill, Refill, and Post-Refill on the current palette. See §8. Painting.

The Tool Options menu for a brush tool, with Macro Locations
The Tool Options menu for a brush tool, with Macro Locations

Drag the handles on the left side of the tool assignment list to change plotting order. The order belongs to this page alone.

Colors, layers, or groups assigned to the same tool plot together without stopping for a tool change.

Tool assignments are shared by name: assigning a tool to “black” assigns it to “black” in every open document. To draw the same color with two different pens, prepare and process those documents separately. See §12.2 What belongs to one document and what belongs to all.

For more about creating, editing, duplicating, and saving tools and toolsets, see §14. The Tool Library.

12.9 Applying tool assignments to every document #

Apply to All, at the right of the TOOL ASSIGNMENTS header, brings the rest of the job into line with the page you are looking at. The button appears only while more than one document is open.

Click Apply to All. Studio asks you to confirm in an Apply Tool Assignments to All Pages dialog, and on OK it sets every color, layer, or group that appears on some other page but not on the page shown in the Preview to None; skip this task, then gives every other page this page's plotting order. Names that this page does not have keep their existing relative order and fall to the end of the list. This cannot be undone.

Apply from the page with the richest set of colors, so that the fewest assignments are lost.

12.10 Path processing options #

The OPTIONS sub-tab controls how Studio processes paths and generates G-Code, and it is divided into two sections. PATH PROCESSING OPTIONS, the first of them, affect how Studio prepares the source geometry before it generates machine motion.

PATH PROCESSING OPTIONS on the OPTIONS sub-tab
PATH PROCESSING OPTIONS on the OPTIONS sub-tab

12.10.1 Hidden Line Removal #

Hidden Line Removal plots only what is visible. (Default: off) When it is on, Studio processes the paths that have a stroke applied and are not hidden behind filled objects, so overlapping shapes, filled areas, and construction geometry covered by another object are left out of the plot rather than drawn through the shapes on top of them.

With it off, Studio processes every path in the file as plottable motion, treating each as stroked and unfilled whatever its appearance in a design program.

For example, with Hidden Line Removal off, a line behind a filled shape still plots, because the underlying path exists in the SVG. With it on, Studio removes the hidden portion, so the output matches the visual appearance of the artwork more closely.

Hidden Line Removal adds processing time, most noticeably on files with many objects, and it can change the direction individual paths are drawn in. Leave it off for artwork with no overlaps, and for calligraphic or brush work, or any application where the path direction should be preserved.

12.10.2 Connect Nearby Ends #

Connect Nearby Ends joins path endpoints that are close together. (Default: on)

It closes tiny gaps where paths nearly meet, which saves pen lifts and keeps lines continuous. Each path is drawn from its start to its finish. Two paths join most simply where one path's finish meets the next path's start. Where two paths finish at the same point, or start at the same point, Studio can still join them by reversing one of the two, so the joined path is drawn in a single direction. It does this automatically unless Preserve Path Orientation is on.

12.10.3 Randomize Starts of Closed Paths #

Randomize Starts of Closed Paths changes the start position of closed shapes. (Default: off)

This spreads the start marks of closed paths around, so they do not stack in one place in repeated patterns, circles, or generative artwork.

12.10.4 Path Reordering #

Path Reordering controls how Studio optimizes stroke order. Reordering paths can reduce travel moves and shorten plotting time.

  • Off — keeps the path order from the SVG file. (Default on HandWriter and WaterColorBot)
  • Optimize speed & quality — balances pen-up travel distance against how evenly strokes are spread across the work area, which reduces visible artifacts from strokes clustering in one region. (Default on ArtFrame and EggBot)
  • Optimize speed only — chooses the order with the least total pen-up travel, however the strokes are distributed.
The Path Reordering menu
The Path Reordering menu

On any machine, choose Off if the exact stroke order matters for your artwork.

12.10.5 Preserve Path Orientation #

Preserve Path Orientation keeps paths moving in the direction defined by the source file. (Default: off) It is unavailable while Hidden Line Removal is on.

Turn it on for calligraphic and brush strokes, and for any work where the direction of drawing changes how a stroke looks. With it off, Studio is free to reverse a path to shorten the pen-up travel before it, or to connect it to a nearby end. With it on, Connect Nearby Ends joins only paths whose directions already line up, so some nearby ends may stay unconnected.

12.11 G-Code generation options #

G-CODE GENERATION OPTIONS, the second half of the OPTIONS sub-tab, affect how Studio writes the final machine instructions.

G-CODE GENERATION OPTIONS
G-CODE GENERATION OPTIONS

12.11.1 Minimize Toolchanges #

Minimize Toolchanges groups operations to reduce the number of times the machine stops for a tool change. (Default: on; off on WaterColorBot)

This is most useful on multi-color and multi-tool jobs, where it cuts the number of stops. Leave it off when the original order of operations is what you want.

12.11.2 Use Curves #

Use Curves allows Studio to generate arc moves where appropriate. (Default: on)

When it is on, Studio fits arcs to the curves in the SVG and writes them as G2 or G3 arc commands, rather than as many short line segments. Arc commands are not available on EggBot's curved drawing surface, so the setting is not available on EggBot, and Studio writes curves as line segments.

Aside

Turn this off when the G-Code goes to a machine or post-processing tool that does not handle arc commands, since every curve is then written as short line segments it can read.

12.11.3 Split by Toolset #

Split by Toolset creates separate output files for each color, layer, or group, depending on the selected sorting method. (Default: off)

Turn it on to run separate files by hand, to control tool order yourself, or to prepare multi-tool jobs for microSD.

The setting applies to the whole job rather than to one page, so with several documents open every page is split. Three documents that each use four pens produce twelve per-tool files, alongside the main output file for each document. For how Studio names the files it writes, see §11.7 Output file names.

12.11.4 Split Long Moves #

Split Long Moves divides long moves into smaller segments. (Default: off)

Shorter moves let the machine respond sooner when you pause it. Artwork with many long moves produces a larger G-Code file.

12.11.5 Disable Rapids #

Disable Rapids replaces rapid pen-up travel moves with controlled feedrate moves. (Default: on)

Travel moves then run at a controlled feedrate rather than the machine's fastest speed, so they are slower but more predictable.

12.11.6 Disable Rapids in Z #

Disable Rapids in Z disables rapid vertical movement when lifting and lowering the pen or tool. (Default: on)

Tool-up and tool-down moves then run at a controlled feedrate. Disable Rapids already includes them, since it turns off rapid moves on every axis.

12.11.7 Index Paper at Start #

Index Paper at Start, for HandWriter jobs, feeds the paper forward and back across the drawing area before writing starts, seating the sheet snugly on the grit rollers that drive it. (Default: off)

This is a mechanical priming step. It does not change the drawn content, and it helps most on a fresh sheet, which has not yet been seated in the rollers.

12.11.8 Eject at End #

Eject at End, for HandWriter jobs, feeds the finished page out at the end of a job, releasing it from the grit rollers. With it off, the page stays in place and the pen returns to the pen loading position. (Default: off)

12.11.9 Pause before lowering pen to install height #

Pause before lowering pen to install height adds a stop to each tool change. (Default: off) When it is on, a tool change pauses with the tool still raised, before it lowers to the install height; resume to lower it and install the tool. This gives you time to remove the previous tool, and keeps a pen from resting on the work surface, where it can leak, while you get ready. The first tool in a job goes straight to its install height without this pause.

12.11.10 Pen Parking Height #

Pen Parking Height controls how high the pen retracts when a plot is paused. It is not shown for EggBot or WaterColorBot.

On HandWriter the pen is installed on the writing surface, so Setup/Install parks the pen on the page, where it can mark the paper during a pause. A warning icon beside the menu says so. Use Pen-up travel on HandWriter.

On HandWriter, Setup/Install shows a warning
On HandWriter, Setup/Install shows a warning

12.12 Preview #

The Preview shows the strokes that will be plotted, written, or painted. It does not show unsupported SVG elements, such as raster images that cannot be plotted as paths.

The Preview includes rulers, zoom controls, the work area, margins, and a visual representation of the generated strokes. Click in the Preview to give it keyboard focus, then zoom and pan from the keyboard. §18.1 Keyboard shortcuts lists the keys and mouse gestures.

The Preview controls are:

  • Zoom percentage: Shows the current zoom level.
  • Zoom out / Zoom in: Changes the preview zoom.
  • Fit: Fits the visible work area into the Preview.
  • RENDER NEW PREVIEW: Draws the writing again from a fresh random pattern, for the page or document you are looking at. It is part of the Bantam Tools Studio Text Add-On, and appears to the right of Fit only when the document contains text and no error is blocking it. See §6.5 Handwriting Defects.
  • ?: Opens a window listing the Preview's keyboard shortcuts and mouse controls.
  • Preview menu: Opens additional rendering options.
  • Page navigator: Appears below the Preview whenever the job runs to more than one page, whether those pages come from several files opened at once, from the documents of a Data Merge, or from one document flowed across several. The inner arrows step a page at a time, the outer arrows jump to the first or last, and typing a number goes straight there.
The Preview toolbar
The Preview toolbar

The Preview's keyboard and mouse controls, from ?
The Preview's keyboard and mouse controls, from ?

While a page is still being drawn, a line above the page navigator reports Rendering… or Updating….

A status line in the Preview's toolbar, to the right of Fit, reports on the job as a whole. It shows an error that stops the job from being prepared, such as a missing font, a Data Merge problem, or a document that runs past the page limit; otherwise how many pages have rendered so far; otherwise a warning that the document contains text or bitmap elements Studio does not draw. When there is nothing to report, the line is hidden.

The status line reports on the job as a whole
The status line reports on the job as a whole

The Preview menu, the three-dot button beside the Preview title, controls how the preview is displayed:

  • Pop Out Preview: Opens the preview in a separate window. While it is open, the main window shows a DOCK PREVIEW button that returns the Preview to the main window; closing the separate window does the same.
  • Show Grid: Shows or hides the grid. (Default: on)
  • Show Axes Label: Shows or hides the X/Y axis label. (Default: on; off on EggBot)
  • Show Ruler: Shows or hides the ruler. (Default: on)
  • 3D Egg Preview: Adds a 3D view below the Preview that shows the artwork wrapped around the object. While it is on, Sphere Shape and Egg Shape choose the shape of the model. Shown for EggBot only. (Default: off)
  • Thin Lines (Better Performance): Displays paths with thin preview lines for better performance. (Default: on)
  • Render SVG Stroke Width: Displays SVG stroke widths in the preview. (Default: off)
  • Use SVG Colors: Displays colors from the original SVG. (Default: on)
  • Use Tool Colors: Displays colors from the assigned tools when available. (Default: off)
  • Re-render all pages: Rerolls every page or document in the job at once. It appears with RENDER NEW PREVIEW when the job runs to more than one page, except for a single document flowed across several pages, which RENDER NEW PREVIEW already rerolls as a whole.
  • Show Plotter: Draws the machine in the preview. Shown for ArtFrame only. (Default: on)
  • Use Built-in Palette SVG (artwork only): Displays the built-in palette SVG when available. (Default: off)
  • Use Generated Palette Preview (shows locations): Displays the generated palette preview when available. (Default: on)
  • Multipage: Neaten Preview Pile: Squares up the stack of pages drawn behind the current one, which otherwise sits at a slight angle. The item appears only while a document runs to more than one page, and it changes the preview alone, never the output. (Default: off)
The Preview menu
The Preview menu

DOCK PREVIEW returns a popped-out Preview to the main window
DOCK PREVIEW returns a popped-out Preview to the main window

Margins and content are draggable in the Preview. Artwork outside the margins is shown in red and is cropped when processed.

Strokes outside the margins are drawn in red and cropped
Strokes outside the margins are drawn in red and cropped

The Preview shows the motion the machine will make: each stroke it will draw, and the travel between strokes. It leaves out anything the machine does not draw, such as fills, and it shows paths rather than how ink or paint will look on the paper.

12.13 The PROCESS AND SAVE button #

When the job is ready, click PROCESS AND SAVE to generate output from the current Setup and Options.

The PROCESS AND SAVE button sits in the upper-right corner of the Studio window. Clicking the button itself processes the current job using the default output behavior; its chevron opens a menu of other save formats.

Processing creates output from the current machine selection, the SETUP sub-tab, the OPTIONS sub-tab, the tool assignments, and the previewed paths. It does not send anything to a machine: the output is written to disk, and uploading is a separate step.

For everything PROCESS AND SAVE can produce — G-Code, SVG, Plob, the Setup Sheet that follows a G-Code export, and the Split by Toolset option — see §11. Exporting output.

For connection and upload workflows, see §10. Sending files to your machine.

12.13.1 Empty pages in a batch #

With more than one document open, Studio checks the pages for plottable strokes before it asks you where to put the output. When it finds pages that have none, an Empty Pages Detected dialog reports how many of how many, and warns that empty pages produce empty G-Code files. Two buttons carry you forward from it, and both go on to the folder picker:

  • Skip Empty Pages — writes nothing for those pages. The batch produces fewer files than you have documents, and the ones it produces keep their own names.
  • Generate All Pages — writes a file for every page, empty ones included. Each empty page's file is valid and contains no motion.
The Empty Pages Detected dialog
The Empty Pages Detected dialog

13. The TEXT tab #

This chapter documents the TEXT tab section by section. Several of its controls require the Text Add-On, and the chapter ends with a section about what the add-on adds.

The TEXT tab is where Bantam Tools Studio™ turns words into strokes a pen can draw. You need it whenever a job carries text: a title on a drawing, a date in the corner, a caption under a diagram, or a signed letter. What follows is reference documentation for each card on the tab; the steps of writing a document are in §6. Writing text.

13.1 The TEXT tab at a glance #

At the top left of the tab, the Enable Text Rendering toggle turns text rendering on and off. (Default: on) To draw the writing again from a fresh random pattern, use RENDER NEW PREVIEW in the Preview's header; see §12.12 Preview.

Below the toggle, two sub-tabs divide the controls. TEXT AND DEFECTS holds everything about how the writing looks, and DATA MERGE holds the tools that fill a template from a CSV file. TEXT AND DEFECTS is selected the first time you open the tab, and Studio remembers which of the two you were last on.

TEXT AND DEFECTS carries four collapsible sections, in this order down the tab:

Apart from Font face, these controls are part of the Bantam Tools Studio Text Add-On, and are grayed out otherwise.

TEXT tab with a text file loaded
TEXT tab with a text file loaded

13.2 What text rendering does #

A pen has no way to set type. When text rendering is on, Studio replaces the text in your document with the paths a pen draws to write it, and those paths are what the machine follows.

The fonts Studio writes with are single-stroke fonts. They are not regular computer fonts, such as the TrueType (.ttf) and OpenType (.otf) fonts installed on your computer.

It is easy to assume otherwise, because on screen even a handwriting-style TrueType or OpenType font looks like it is made of strokes. A t and an x each look like two strokes crossing, and an O looks like one loop. They are not. In a regular computer font, the t and the x are each a single complicated closed outline, and the O is two closed outlines, one inside the other. The shape you see is the space between the edges, filled in, which is why these are also called outline fonts. There is nothing in the file that describes the line down the middle of a letter, which is the one thing a pen needs.

A single-stroke font stores that centerline instead. The pen travels each letter once rather than tracing its edge and filling the inside, which is what makes writing practical on a plotter, and why the letters come out as line work rather than as solid shapes.

The Preview area shows those strokes, which is why text on the TEXT tab looks thinner and plainer than the same words in a design program or a word processor. Studio is showing you machine motion, not a picture of finished ink. The tool and the paper decide how heavy the finished line looks.

Two single-stroke fonts are included: Hershey Sans 1-stroke and Hershey Script 1-stroke. Choose between them with Font face, in the FONT section. The Bantam Tools Studio Text Add-On opens the full font library, and a document's own font names then select from it; see §6.4 Font selection.

A title written in Hershey Sans 1-stroke
A title written in Hershey Sans 1-stroke

The same title in Hershey Script 1-stroke
The same title in Hershey Script 1-stroke

The words themselves reach Studio in the document you open: text placed in an SVG file by an editor such as Inkscape or Adobe Illustrator, a .txt or .rtf file, or text pasted from the clipboard.

Text rendering sets how the words are drawn, not what they say. Nothing on the TEXT tab edits the text itself — to change the wording, change the document and open it again.

With the toggle off, Studio passes the document through untouched. Nothing converts the words into strokes, so the job carries the rest of the artwork and none of the writing. That is the setting to check first if a drawing plots correctly but arrives with its title missing.

Enable Text Rendering off: the drawing's title is missing from the Preview
Enable Text Rendering off: the drawing's title is missing from the Preview

The same drawing with Enable Text Rendering on
The same drawing with Enable Text Rendering on

Turning Enable Text Rendering off does not discard your setup. Studio leaves your spacing, overflow, and merge settings exactly as you left them, so turning the toggle back on restores the document without a second pass through the sections. You can use it freely to compare a drawing with and without its writing.

13.3 Writing text in an SVG file #

In an SVG file, the writing is one part of a larger drawing: a title, a date in the corner, a caption, an edition number on a print in a series, a label on a diagram, a short quote. It is also how you see what Studio does with text, and how the two included Hershey fonts look on paper.

Place the text in your artwork in an SVG editor such as Inkscape or Adobe Illustrator, save or export the file as an SVG, and then:

  1. Open the SVG file in Bantam Tools Studio.
  2. Go to the TEXT tab and turn on Enable Text Rendering.
  3. Confirm the font in the FONT section header.
  4. Go to the PREPARE tab and confirm the page setup, along with the scale and position of the artwork on the page.
  5. Confirm the toolset and the tool assignments, so the writing is drawn with the tool you mean it to be drawn with.
  6. Check the Preview. The writing appears as the strokes the tool will follow.
  7. Click PROCESS AND SAVE.

Studio generates the job from the document as the Preview showed it, writing and artwork together.

An SVG document's text on the TEXT tab: the FONT section offers no font size
An SVG document's text on the TEXT tab: the FONT section offers no font size

A document whose text arrives from the clipboard or from a .txt or .rtf file is handled the same way once it is open, and it can run longer than a single page. Bringing text in by those routes, and what Studio does when the words outrun the space they have, are covered in §6. Writing text.

13.4 Signatures #

A signature is real handwriting that Studio draws wherever you ask for it. It can come from a signature file you load, or from the font you write in.

To sign a document:

  1. Open the SIGNATURE section.
  2. Click SELECT and choose your signature file. Studio accepts .svg and .zip files.
  3. Set Size with the slider or the field beside it. The range is 50% to 500%, measured against normal text height, so 100% draws the signature at the size of the surrounding writing.
  4. In the text of your document, put {{sig}} where the signature belongs.
The SIGNATURE section before a file is loaded
The SIGNATURE section before a file is loaded

Studio draws the signature in place of {{sig}}, at the size you set, and the section header changes from "No separate file selected" to the name of the file you loaded, with the extension dropped: MySignature.svg reads as MySignature. If the file cannot be used, Studio says so and leaves the section empty rather than accepting a signature it cannot draw.

The usual place for {{sig}} is on its own line after a closing:

Warmly,
{{sig}}

{{sig}} is not limited to one document. Set it up in a letter template and every personalized letter generated from that template is signed, with no per-letter step. {{sig}}, {{sigalt}}, and {{siginit}} are built-in names, so a CSV column named sig, sigalt, or siginit is ignored, and Studio tells you when it sees one.

Size is measured against the writing, not against the page, so a signature keeps its proportions when the rest of the document is scaled to fit. Set it a little larger than 100% if you want the signature to read as a signature rather than as another line of text, and check the result in the Preview before committing a batch to paper.

The signature drawn in place of {{sig}}
The signature drawn in place of {{sig}}

Use the trash button beside the file name to clear a loaded signature. The section returns to "No separate file selected", and {{sig}} falls back to the font's signature. If the font has none, Studio reports a Signature issue.

13.4.1 Signatures included in a font #

Some fonts include a signature, and some also include an alternate signature and initials. Fonts made in Bantam Tools Font Maker for iPad include whichever of these you wrote. A signature command draws each one:

{{sig}}, {{sigalt}}, and {{siginit}} are not merge fields, though they are written like them. A merge field such as {{first_name}} is filled from a CSV file. A signature command is not: a CSV file is never required for {{sig}}, {{sigalt}}, or {{siginit}}, and they work in any document, with or without Data Merge.

{{sigalt}} and {{siginit}} always come from the font; a loaded signature file replaces {{sig}} only. Size applies to all three.

If the font cannot supply what a signature command asks for, such as {{siginit}} in a font without initials, Studio does not generate the job. PROCESS AND SAVE reads Signature issue, and the CSV DATA PREVIEW section on the DATA MERGE sub-tab names the command and the font; the section appears for this even when Data Merge is off. Choose a font that includes it, load a signature file (for {{sig}}), or remove the command.

Tip

For the best result, use a clean .svg made from a real signature rather than a traced photograph of one. Bantam Tools Font Maker for iPad produces this kind of file, and the support article on capturing handwriting and signatures, in the Bantam Tools support section online, covers the process end to end.

SIGNATURE section with a signature file loaded
SIGNATURE section with a signature file loaded

13.5 About the Text Add-On #

Every copy of Bantam Tools Studio writes the text an SVG document already carries, in the two included Hershey fonts. That is enough for a title or a caption on a page you designed yourself. The Bantam Tools Studio Text Add-On unlocks the rest of the TEXT tab, and each of its pieces answers a job the base license cannot do:

The Text Add-On is a separate purchase for Bantam Tools Studio, and is included with every Bantam Tools HandWriter®. Visit bantamtools.com/text for more information.

§6. Writing text takes those controls in the order they appear down the tab, from bringing text in through font, defects, spacing, and multipage flow. §7. Data Merge covers filling one document from a CSV file to produce a batch.

14. The Tool Library #

The Tool Library, in Bantam Tools Studio™, is where you look through your tools, choose them, and create your own — the pens, markers, and brushes your machine holds — along with the settings for drawing with each one. Open it from the TOOLS tab (⌘3 / Ctrl+3), or from the View menu.

The preset toolsets are tuned for each machine and for the tools we recommend, and are ready to use as they are. To change one, copy it into a toolset of your own.

Editing a tool changes what it does the next time it is used. Choosing which tool draws which part of your artwork happens on the PREPARE tab.

A small line at the top of the tool list — "Click a Toolset to expand / edit." — is your reminder that toolsets are collapsible; click one to reveal the tools inside it. A status line at the bottom of the tool list also shows which tool and toolset are currently selected.

TOOLS tab with the Black G2-0.7 tool open in the Tool Editor
TOOLS tab with the Black G2-0.7 tool open in the Tool Editor

14.1 Preset and user toolsets #

The tool list is organized into three sections:

UNGROUPED TOOLS is also a catch-all: put tools there and you can use them together, if you want every one of your tools available all the time. Toolsets keep each job's choices clear, though. For example, you might keep one toolset of gel pens in different colors, another of fiber-tip markers, and one for each set of paints.

You can change a preset tool's fields and plot with the result, but changes to preset toolsets and their tools are not saved: the values revert when you quit Studio. Selecting one shows a banner reading "Preset Tool" or "Preset Toolset" that says so. To keep your changes, use Copy to, in the three-dot menu, to make an editable copy.

The banner on a preset tool
The banner on a preset tool

Each machine's section of the tool setup reference lists its preset toolsets; see §15. Tool setup reference.

14.2 Creating and duplicating toolsets #

To start a new toolset, click Create new toolset under User Toolsets. The Create New Toolset dialog asks for:

  • Toolset Name
  • Based on: Choose None - create empty toolset, or pick any existing user or preset toolset to start from a copy of it.

Click CREATE TOOLSET to finish, or CANCEL to back out. The new toolset appears under USER TOOLSETS, selected and ready to edit.

The Create New Toolset dialog
The Create New Toolset dialog

Clicking the menu button on a toolset gives you:

  • Use This Toolset — makes it the active toolset for the current job.
  • Add Tool — adds a new tool to that toolset. A small dialog lets you name the new tool and optionally base its starting settings on another toolset.
  • Duplicate Toolset — copies the toolset, including preset toolsets.
  • Delete Toolset — available for user toolsets only.
The menu on a user toolset
The menu on a user toolset

Add Tool opens the Create New Tool dialog
Add Tool opens the Create New Tool dialog

We recommend duplicating a preset rather than building a toolset from scratch, since the preset's heights and feedrates are already close to correct for the tool it was tuned around; start empty only when your tool has nothing in common with any preset.

Name new toolsets clearly so they are easy to identify later. Useful names might include the tool type, material, machine, or workflow.

14.3 Importing and exporting toolsets #

The editor header shows four buttons: ABOUT, SAVE CHANGES, IMPORT, and EXPORT. SAVE CHANGES and EXPORT stay grayed out until a tool or toolset is selected.

  • IMPORT brings in a JSON file containing a previously exported tool or toolset. An Import from JSON dialog first asks what the file holds: click TOOL or TOOLSET, then choose the file.
    • For a tool, an Import Tool dialog asks where to store it. Choose Main Library (No Toolset) or a toolset from the list, then click IMPORT.
    • For a toolset, if a toolset with the same name and identifier already exists, Studio asks whether to Overwrite it (keeping your current tool assignments) or Import as New (create a separate copy with a new identifier).
  • EXPORT becomes available once you select a tool or toolset, and saves it as a JSON file. When the export finishes, Open File Location shows the saved file.
The editor header buttons
The editor header buttons

Importing a toolset that already exists: Overwrite or Import as New
Importing a toolset that already exists: Overwrite or Import as New

An exported JSON file holds a toolset's tuned settings outside Studio, so it can back up a custom toolset before a software update, move your pens to another computer, or give a teammate the same calibration.

ABOUT opens a short explainer covering how tools and toolsets relate: toolsets let you adjust settings like feedrate or pen up height across every tool in the set at once, and when Sort Strokes by Color is active, Studio automatically matches each tool to the closest color in your source file.

The About the Tool Library dialog
The About the Tool Library dialog

14.4 Editing a whole toolset #

Select the toolset itself, rather than a tool inside it, to edit settings shared across every tool in that set. For example, you can raise every tool's feedrate at once while leaving each tool's individual pen heights untouched.

If the tools in a toolset currently have different values for a field, that field shows "Various" until you enter a new value — at which point the new value applies to every tool in the set. Leaving a "Various" field alone is safe: it is not a value, and nothing is written to the tools underneath it.

Click SAVE CHANGES before leaving the page. A confirmation lists each changed setting's current and new value before the changes are applied. Checking Don't show this again in it saves later changes without the list. If the toolset is not the one selected on the PREPARE tab, the confirmation also offers Use this toolset in Prepare, which selects the toolset there once it is saved. Your choice is remembered for later saves. Hold ⌥ (Option) while your pointer is over the button (Alt on Windows) to change it to REVERT, which discards your pending edits instead of saving them.

The confirmation before a toolset's changes are saved, listing each setting's current and new value
The confirmation before a toolset's changes are saved, listing each setting's current and new value

If you leave a tool or toolset with unsaved edits, a separate Unsaved Changes prompt asks what to do with them. Checking Don't show this again (always discard) in that prompt discards unsaved edits without asking from then on.

14.5 Editing an individual tool #

Select a tool to edit its settings. For example, you can rename the tool, change its color, or have the machine pause for it at a tool change:

A tool's Tool Name, Tool Category, Color, and Hold Position on Tool Change
A tool's Tool Name, Tool Category, Color, and Hold Position on Tool Change

The rest of a tool's settings, including its heights, speeds, and refills, are in its Tool Settings section. Each machine's heights and speeds are covered machine by machine; see §15. Tool setup reference.

Tip

Click or hover over any field to see a short description of what it does at the top of the panel.

Clicking a field describes it at the top of the panel
Clicking a field describes it at the top of the panel

Refill Mode, also in Tool Settings, sets whether and how often the tool stops to refill:

  • No Refills
  • Refill by Distance — the field reads Refill Distance: how far the tool draws before it refills, where 0 turns refills off. The refill comes at that exact distance, wherever it falls: at the start, the middle, or the end of a stroke. Afterward, the tool returns to the point where it stopped and continues the stroke.
  • Refill by Stroke — the field reads Refill After Strokes: how many strokes the tool draws between refills. Refills come only between strokes, so a stroke is never interrupted, however long it is.
The Refill Mode menu
The Refill Mode menu

A units menu beside Refill Distance chooses whether the distance is shown in mm or m, or in inches, feet, or yards. The menu changes only how the distance is displayed, not the distance itself.

What a refill does, and when it is useful, depends on the machine; see §15. Tool setup reference. A tool you create with Add Tool starts at Refill by Distance, with a distance of 600 m.

The units menu beside Refill Distance
The units menu beside Refill Distance

14.6 The Metadata section #

The Metadata section starts collapsed. Click it to expand a few descriptive fields:

On WaterColorBot, Tool Type is limited to Paintbrush.

Apart from Tool Type, these fields do not change how a tool plots. Tool Type also sets Tool Category: Paintbrush makes the tool a brush, and the other types, apart from Other, make it a pen. Tool Width and Tool Type help you sort and identify tools at a glance; Manufacturer, Version, and Description are notes for your own reference.

The Metadata section, expanded
The Metadata section, expanded

The Tool Type menu
The Tool Type menu

14.7 Pen Landing & Lift #

This section appears on the ArtFrame and HandWriter. The EggBot and WaterColorBot lift their tools with a servo and do not use it.

The Pen Landing & Lift section, below Tool Settings, shapes how the tool meets and leaves the paper:

The Pen Landing & Lift section
The Pen Landing & Lift section

Start from the preset values. Make the move gentler — a higher Approach Above Paper, a slower Touchdown Speed, or turning on Soft Lift — when you see blobbed stroke ends, a visible bounce, or noise at the top of the lift. Each step costs a little plotting time.

14.8 Copying and moving tools #

Open the menu button on a tool row for:

  • Duplicate
  • Copy to
  • Move to
  • Delete
The menu on a tool row
The menu on a tool row

Duplicate, Move to, and Delete are available only for custom (user-created) tools. Copy to works on any tool, including presets — it is how you make an editable copy of a preset tool without disturbing the original.

Choosing Copy to or Move to opens the Manage Tool dialog, where you pick a destination from a list of your toolsets. Ungrouped Tools is always listed, if you just need a place for the tool.

The Manage Tool dialog, with the destination selector
The Manage Tool dialog, with the destination selector

Copying leaves the original tool in place and adds a copy at the destination; moving removes the tool from its current toolset and files it under the destination instead. Neither one changes the tool's settings, and neither affects a job you have already processed.

14.9 The PALETTES tab #

The PALETTES tab lists your palettes. Use it to preview, copy, import, and export them. It appears on ArtFrame and WaterColorBot.

A palette is the tray of numbered wells, holding paint and water, that a brush visits between strokes. A palette in Studio records where each numbered location sits, not what is in it. Tools supply the rest: each brush tool is told which locations it refills, primes, and washes at, and a location takes on the color of the tool that refills there. Those assignments belong to the tools, and are set in each tool's Tool Macro Setup. See §8.8.1 Assigning palette locations to a tool.

The PALETTES tab
The PALETTES tab

14.9.1 Default and user palettes #

The list on the left has two sections:

Click a palette to preview it. Selecting a palette also makes it the active palette used for plotting, the same palette chosen by the Palette menu on the PREPARE tab and the palette menu in Tool Macro Setup. Selecting a palette does not assign any tool to it; a brush still dips where its own macros say it dips. On ArtFrame, with a brush toolset, the paper offset moves to make room for the palette; see §12. The PREPARE tab.

Right-click a palette, or click its menu button, for more actions; see §14.9.3 Duplicating, renaming, and deleting palettes.

14.9.2 The palette preview #

The right side of the tab, titled Palette Library, shows the selected palette:

Hover over a location to see which tools use it and for what.

To see a different toolset's assignments, select that toolset on the TOOLS tab, then return to PALETTES.

14.9.3 Duplicating, renaming, and deleting palettes #

The menu for a default palette offers Duplicate. The menu for a user palette offers Duplicate, Rename, and Delete.

The menu on a user palette
The menu on a user palette
  • Duplicate: Copies the palette into USER PALETTES with "(Copy)" added to its name, and selects the copy. Duplicate a default palette to get one you can rename.
  • Rename: Opens the Rename Palette dialog. Enter a new Palette Name and click RENAME. Tool assignments are unaffected, since tools follow the palette itself rather than its name.
  • Delete: Opens the Delete Palette dialog, which reports how many tools in the current toolset use the palette. Click DELETE to delete it.
The Delete Palette dialog, naming the palette and the tools that use it
The Delete Palette dialog, naming the palette and the tools that use it

Important note

Deleting a palette cannot be undone, and tools that used it lose their locations for it. Export a palette you may want back before you delete it.

A copy starts with every location unassigned. Tool assignments point at one specific palette and do not follow a duplicate, so after duplicating, select each tool on the TOOLS tab and assign its locations on the copy.

14.9.4 Importing and exporting palettes #

The IMPORT and EXPORT buttons, at the top of the preview, move palettes in and out of Studio as JSON files, to back up a palette or share it with another computer.

If the imported palette is one Studio already has, a Palette Already Exists dialog asks what to do:

  • Import as Copy — adds a new, separate palette with a unique name. The existing palette and its tool assignments are unaffected.
  • Replace — updates the existing palette with the imported locations, and keeps the tool assignments that point at it. Offered only when the existing palette is a user palette.
The Palette Already Exists dialog
The Palette Already Exists dialog

For a palette without its own artwork, a SAVE AS SVG button below the preview saves the preview diagram as an SVG file: the palette's numbered locations, drawn to size, without tool colors.

14.10 Testing tool settings #

Two features make testing settings quicker:

To match what you see to the setting most likely to fix it, see each machine's section of the tool setup reference (§15. Tool setup reference).

15. Tool setup reference #

Each machine holds and moves its tool in its own way, so each has its own tool settings and its own way of setting up a tool. An ArtFrame tool is installed on the Pen Height Setup Tool; an EggBot pen draws on a curved surface; a HandWriter pen rides on a spring; a WaterColorBot brush paints at a fixed height, set by where it sits in its holder.

The sections that follow cover the tool settings for each machine.

15.1 ArtFrame tool setup #

You set how the Bantam Tools ArtFrame™ handles each pen and brush: how high it lifts between strokes, how it meets the paper, how fast it moves, and what it does at a tool change or a refill. These settings belong to each tool, in the Tool Library of Bantam Tools Studio™.

Every tool starts with one physical step: installing it with its tip resting on the Pen Height Setup Tool. The tool's setup height is the thickness of that tool, so that you know the distance between the pen and your paper; the tool's other heights are measured from the paper.

For installing a tool at height, see the Bantam Tools ArtFrame guide (bantam.tools/afguide).

The preset toolsets are tuned for the ArtFrame; choose the one that matches your pens or brushes, and use it as it is. This chapter explains their settings, and how to tune a tool of your own.

15.1.1 Preset toolsets #

The ArtFrame has six preset toolsets:

Pilot G2 is selected to start with.

15.1.2 Pens and brushes #

A tool's Tool Category is Pen or Brush. The category decides how the tool meets the paper, and which settings the tool editor shows:

The Tool Type menu in the Metadata section also sets the category: Paintbrush makes the tool a brush, and Ballpoint, Fountain, Gel, Felt Tip, and Calligraphy make it a pen.

15.1.3 Setting the setup height #

For a pen, set the setup height (Setup Block/Park Height, as it reads by default) to the thickness the tip rested on when you installed it: 3.5 mm with either side of the Pen Height Setup Tool. That tells the machine where the paper is. When the pen draws, the machine lowers it past the paper by its Draw Depth, compressing either the pen itself or a spring in its holder, depending on how the pen is mounted.

A brush has no Draw Depth. You set how firmly it meets the paper when you install it: lower the brush onto the Pen Height Setup Tool as far as you want it to press against the paper later. A light touch on the tool gives a light touch on the surface, and bristles that bend against the tool bend the same way against the surface. The brush presets add a little more: they paint slightly lower than the height you installed the brush at, so the bristles deflect a bit farther against the paper than they did on the tool.

15.1.4 Pen heights #

A pen's heights are distances from the paper:

With Enable Absolute Z Positions on, in Tool Settings, the same heights show as positions on the ArtFrame's Z axis instead: Pen Up Height, Setup Height, and Pen Down Height, where the tip meets the paper. Z Offset is hidden. The setting applies to every tool and changes only how heights are shown, never what is stored. (Default: off)

Tool Settings for an ArtFrame pen, with relative heights
Tool Settings for an ArtFrame pen, with relative heights

Tool Settings for an ArtFrame pen, with Enable Absolute Z Positions on
Tool Settings for an ArtFrame pen, with Enable Absolute Z Positions on

These are the names with Pen Parking Height at its default; two of them change with that setting (see §15.1.6 Parking during a pause).

15.1.5 Brush heights #

A brush's heights are measured from its Painting height, where the brush sits on the ArtFrame's Z axis while it paints. In the order Tool Settings shows them:

With Enable Absolute Z Positions on, all five show as positions on the Z axis: Pen Up/Park, Setup Height, Painting height, Paint dip height, and Water dip height. Changing Painting height there moves only the painting height; the brush's other heights stay where they are.

Tool Settings for an ArtFrame brush, with relative heights
Tool Settings for an ArtFrame brush, with relative heights

15.1.6 Parking during a pause #

The parking height is where the tool waits when you pause a job, lifted clear of the paper until you resume. For a pen, choose that height with Pen Parking Height, in G-CODE GENERATION OPTIONS on the PREPARE tab's OPTIONS sub-tab:

The field that holds the parking height adds "Park" to its name: Setup Block/Park Height (Setup/Park Height with absolute heights) or Pen Up/Park Height.

A brush always parks at its travel height, Pen Up/Park, whatever this setting says.

15.1.7 Speed and acceleration #

Both are whole numbers. A tool that draws cleanly at a moderate speed may skip when it moves faster than its ink or paint can keep up.

15.1.8 Tool changes and refills #

15.1.9 Tuning a pen or brush #

Tune a tool on scrap paper, starting from the preset closest to it:

  1. Copy the tool into a toolset of your own, or duplicate its toolset.
  2. Draw a short test, such as a few lines or shapes like the ones in your artwork.
  3. Change one setting at a time, and draw the test again after each change.
  4. When the result looks right, save your changes. Export the toolset to keep a backup.

Match what you see to the setting most likely to fix it:

15.2 EggBot tool setup #

You set how the Bantam Tools EggBot™ handles each pen: how high it lifts between strokes, how far it reaches toward the object, how fast the object turns and the pen arm swings, and what it does at a pen change. These settings belong to each tool, in the Tool Library of Bantam Tools Studio™.

The preset toolsets are tuned for the EggBot; choose the one that matches your pens, and use it as it is. This chapter explains their settings, and how to tune a pen of your own.

For how the pen is installed and aligned, see the Bantam Tools EggBot guide (bantam.tools/ebdocs).

15.2.1 Preset toolsets #

The EggBot has two preset toolsets, both for felt-tip pens: Sharpie - UltraFine and Micron - 0.5/0.8. Sharpie - UltraFine is selected to start with.

In Tool Settings, leave Tool Category set to Pen; every EggBot tool is a pen.

15.2.2 Pen heights #

The EggBot raises and lowers its pen with the pen-lift servo. A pen's heights are distances along that lift, in millimeters:

With Enable Absolute Z Positions on, in Tool Settings, the same heights show as positions on the pen lift's range instead: Pen Up/Park Height and Pen Down Height, where the tip meets the surface. Z Offset is hidden. The setting applies to every tool and changes only how heights are shown, never what is stored. (Default: off)

Tool Settings for an EggBot pen, with relative heights
Tool Settings for an EggBot pen, with relative heights

Tool Settings for an EggBot pen, with Enable Absolute Z Positions on
Tool Settings for an EggBot pen, with Enable Absolute Z Positions on

A pen is installed at its travel height, so the EggBot has no setup height to enter.

15.2.3 Speed and acceleration #

Both are whole numbers. A pen that draws cleanly at a moderate speed may skip when it moves faster than its ink can keep up.

15.2.4 Pen changes and pauses #

15.2.5 Tuning a pen #

Tune a pen on a spare object, starting from the preset closest to it:

  1. Copy the tool into a toolset of your own, or duplicate its toolset.
  2. Plot a short test, such as a few lines around the object.
  3. Change one setting at a time, and plot the test again after each change.
  4. When the result looks right, save your changes. Export the toolset to keep a backup.

Match what you see to the setting most likely to fix it:

15.3 HandWriter tool setup #

You set how the Bantam Tools HandWriter® handles the pen: how high it lifts between strokes, how hard it presses on the paper, how fast it moves, and what it does at a pen change. These settings belong to each tool, in the Tool Library of Bantam Tools Studio™.

The preset toolsets are tuned for the HandWriter; choose the one that matches your pen, and use it as it is. This chapter explains their settings, and how to tune a pen of your own.

For how the pen is physically installed, see the Bantam Tools HandWriter guide (bantam.tools/hwdocs).

15.3.1 Preset toolsets #

The HandWriter has six preset toolsets, three for each of two pens:

Normal balances speed and quality. High Speed moves faster, for quicker writing, and Graphics moves more gently, for precise detail. Pilot G2 — Normal is selected to start with.

15.3.2 Pen heights #

The HandWriter's pen heights are measured from the point where the pen tip meets the paper. You set that point when you load the pen with its tip touching the paper, so there is no separate setup height to enter.

Each tool has two heights:

The two heights share the machine's range of travel. If a tool asks for more than fits, its pressure is reduced to fit, and a warning appears beside Pressure Depth, headed Z ceiling, that names the pressure it will use. Lower Pressure Depth or Pen Up/Park Height to clear it.

Tool Settings for a HandWriter pen: Pen Up/Park Height and Pressure Depth
Tool Settings for a HandWriter pen: Pen Up/Park Height and Pressure Depth

15.3.3 Pen pressure and pen type #

The right amount of pressure depends on the pen, and the two preset pens sit at opposite ends:

When you try a pen that isn't covered by a preset, start from the preset for the pen type it most resembles. Open its toolset on the TOOLS tab to see the current values.

15.3.4 Speed and acceleration #

Speed and ink flow are linked. A pen that writes cleanly at a moderate speed may skip when it moves too fast for its ink to keep up. These are the values that differ most between a pen's three preset tiers; see §15.3.1 Preset toolsets.

If an orange warning icon appears beside the Z feedrate or acceleration, that combination is fast enough that long pen lifts can lose steps (the motor slips and loses track of its position) and leave the pen short of a full lift. Hover over the icon to see which values to lower.

15.3.5 How the pen meets and leaves the paper #

Each pen preset sets how the pen meets and leaves the paper, so most writing never needs these settings changed. They work together like this:

These settings are in the tool editor's Pen Landing & Lift section; see §14.7 Pen Landing & Lift.

15.3.6 Pen changes and pauses #

  • Hold Position on Tool Change, on each tool, makes the HandWriter stop at the pen loading position and prompt you on the display when a job switches to that pen. Every preset tool has it on; a tool you create from scratch starts with it off. The Bantam Tools HandWriter guide covers loading the next pen.
  • Pause before lowering pen to install height, in G-CODE GENERATION OPTIONS on the PREPARE tab's OPTIONS sub-tab, adds a stop to each pen change after the first. The HandWriter pauses with the pen raised, before lowering to install height, and continues when you resume. This keeps the pen tip off the paper, where it could leak, while you get ready. (Default: off)
  • Pen Parking Height, in the same section, sets where the pen waits when you pause a job. Pen-up travel parks the pen at its Pen Up/Park Height. (Default: Pen-up travel) Because the pen is installed with its tip on the paper, Setup/Install would park it on the page, where it could mark the paper. Studio shows a warning beside the menu if you choose it.
Pen Parking Height menu with Setup/Install chosen, and the warning beside it
Pen Parking Height menu with Setup/Install chosen, and the warning beside it

Refills are rarely needed on the HandWriter, so the presets are set to No Refills. They can come in handy, for example to swap in a fresh pen partway through a long batch of letters: set a Refill Distance, and when the pen has written that far, the HandWriter lifts it, moves to the pen loading position, and pauses so you can put in a fresh pen, then continues where it stopped.

15.3.7 Tuning a pen #

Tune a pen on scrap paper, starting from the preset closest to it:

  1. Copy the tool into a toolset of your own, or duplicate its toolset.
  2. Write a short test: a few lines of text in the size and font you plan to use.
  3. Change one setting at a time, and write the test again after each change.
  4. When the result looks right, save your changes. Export the toolset to keep a backup.

Match what you see to the setting most likely to fix it:

15.4 WaterColorBot tool setup #

You set how the Bantam Tools WaterColorBot™ handles each brush: how high it lifts between strokes, how deep it dips into water and paint, how fast it moves, and what it does at a brush change or a refill. These settings belong to each tool, in the Tool Library of Bantam Tools Studio™.

The preset toolsets are tuned for the WaterColorBot; choose the one that matches how you want to paint, and use it as it is. This chapter explains their settings, and how to tune a brush of your own.

15.4.1 Preset toolsets #

The WaterColorBot has six preset toolsets:

See §8.7 Preset painting toolsets. Loaded Brush (Wet) is selected to start with.

Every WaterColorBot tool is a brush: Tool Category is Brush, and Tool Type is Paintbrush.

15.4.2 Brush heights #

The WaterColorBot paints at a fixed painting height, and a brush's other heights are measured from it:

The painting height is not a setting. How firmly the brush meets the paper is set by where it sits in its holder: the WaterColorBot holds the brush at the painting height while you install it. The Bantam Tools WaterColorBot guide (bantam.tools/wcbdocs) describes setting the brush in its holder.

With Enable Absolute Z Positions on, in Tool Settings, the heights show as positions on the brush lift's range instead: Pen Up/Park Height, Paint dip height, and Water dip height. The painting height appears with them, for reference, as Painting height (fixed). The setting applies to every tool and changes only how heights are shown, never what is stored. (Default: off)

Tool Settings for a WaterColorBot brush, with relative heights
Tool Settings for a WaterColorBot brush, with relative heights

Tool Settings for a WaterColorBot brush, with Enable Absolute Z Positions on
Tool Settings for a WaterColorBot brush, with Enable Absolute Z Positions on

15.4.3 Speed and acceleration #

Both are whole numbers. Slower strokes lay down more paint; see §8.2.2 Speed affects saturation.

15.4.4 Brush changes and refills #

15.4.5 Tuning a brush #

Tune a brush on scrap paper, starting from the preset closest to what you want:

  1. Copy the tool into a toolset of your own, or duplicate its toolset.
  2. Paint a short test, such as a few strokes in each color you plan to use.
  3. Change one setting at a time, and paint the test again after each change.
  4. When the result looks right, save your changes. Export the toolset to keep a backup.

Match what you see to what most likely fixes it:

16. The MACHINE tab #

The MACHINE tab (⌘4 / Ctrl+4) is where you connect Bantam Tools Studio™ to a machine, control it directly, browse the files stored on it, and manage the jobs Studio has queued for it. This chapter documents every control on the tab, in the order the tab presents them. For the practical question of which of the three routes — microSD card, USB, or WiFi — to use for a given job, see §10. Sending files to your machine.

The tab is hidden by default, so turn it on before you connect a machine for the first time:

Settings → Machine Control → Show Machine Control Tab

A small colored dot overlays the MACHINE tab label itself: blue means a machine is connected, tangerine means Studio is connecting, and gray means no machine is connected. The dot stays visible no matter which tab you're viewing, so you always know your connection status at a glance.

Below the connection row, the tab splits into two sub-tabs:

The Preview stays visible on the right side of the window in either sub-tab, so you can still see the current job while you connect, upload, or manage the queue.

MACHINE tab with a plotter connected over USB
MACHINE tab with a plotter connected over USB

16.1 Connecting to a machine #

At the top of the MACHINE tab, a Connect split button offers four ways to reach a machine:

Clicking the Connect button itself, rather than opening its menu, favors USB: if a machine is available over USB, Studio connects to it directly; otherwise it falls back to WiFi, using the manual IP field if you've entered one. While Studio is connecting, the button area shows a spinner and a Cancel button so you can back out.

Once connected, Connect is replaced by a Disconnect split button, whose own menu still offers Setup New Plotter so you can add another machine without disconnecting first. Beside it, Studio shows the connection type — USB Serial or WiFi — and a drop-down menu listing any other machines discovered on your network.

If Studio can't reach a machine, or a connection problem persists, an error line reading BT-<code> — <summary> appears beneath the connection row, with Try Again and Copy Diagnostics buttons. Try Again repeats the attempt without changing anything; for an error that needs a step at the machine first, such as BT-205, the message says what to do. Copy Diagnostics puts the full error text on the clipboard, which is what Bantam Tools support will ask you for. When one of these errors closes the connection, the line moves to the top of the CONTROLS sub-tab, above Plotters on network.

Connect menu on the MACHINE tab
Connect menu on the MACHINE tab

16.2 Connecting over USB #

To connect over USB:

  1. Connect the machine to your computer with a USB cable.
  2. Open the MACHINE tab.
  3. Click Connect, then choose Connect via USB — or click Connect alone, since USB is favored automatically when available.

The connection row then shows USB Serial and the machine's status, and the machine controls become active.

16.3 Connecting over WiFi #

To connect over WiFi:

  1. Open the MACHINE tab.
  2. Click Connect, then choose Scan for Plotters.
  3. Select the machine from the results.

The popup closes and the connection row shows WiFi with the machine's status.

If no machine is connected yet, the CONTROLS sub-tab shows a Plotters on network list of every machine Studio has discovered, each with its own Connect button — a quicker path than opening the scan popup. If nothing turns up, it reads No plotters found on this network. Confirm the computer and the machine are on the same WiFi network, then try again.

You can also skip discovery entirely and choose Enter IP from the Connect menu to connect by address. That is the route to use on a network whose devices cannot see each other's discovery traffic, since the address works even where the scan finds nothing.

MACHINE tab with no plotter connected
MACHINE tab with no plotter connected

16.4 Setting up a new plotter #

Setup New Plotter, on both the Connect and Disconnect menus, opens the Set Up Your Plotter dialog, which gives a machine the settings it needs to join a WiFi network. For the walkthrough, and for choosing between delivering the settings over USB or on a microSD card, see §10.6 Putting your machine on a network. The dialog's controls:

Setup New Plotter on the Disconnect menu
Setup New Plotter on the Disconnect menu

Note

Setup configures the machine's network settings; it does not move any of your work onto the machine. Files still travel by microSD card, USB, or WiFi upload afterward.

WiFi step of the Set Up Your Plotter dialog
WiFi step of the Set Up Your Plotter dialog

16.5 Machine controls #

Once connected, the CONTROLS sub-tab shows a status line reading Status followed by the machine's current state, such as Idle, Plotting, Paused, or Alarm. On a machine that homes, the status line adds (homed) or (unhomed) while the machine is Idle or in an Alarm state, so you know whether to home it before the next plot.

The available machine controls are:

Studio has no jog controls — it does not drive the machine's motors manually, one step at a time.

While a job is plotting, a progress bar and percentage appear beside the status line. When the machine goes a few seconds without reporting its progress, a short segment sweeps along the bar in place of the fill, and the percentage gives way to the time elapsed since the plot began, such as 12:05. While a plot is paused, the bar holds its last position and the percentage is hidden.

If the machine pauses mid-job for a pen or tool change — a multi-tool job, for example — the instruction the machine itself is showing (such as which pen to install next) appears in orange beneath the status line, marked with a pen glyph. It stays there until you make the change and click Continue.

CONTROLS sub-tab during a plot, with its progress bar
CONTROLS sub-tab during a plot, with its progress bar

16.6 Files stored on the machine #

Below the machine controls, the Files section lists what's stored on the machine's microSD card — G-Code files and folders, including any Studio has organized into subfolders. A check mark next to a file means the machine has already plotted it. This is the same list, and the same set of check marks, that the machine's own display shows; the user guide for your machine covers browsing and running those files at the machine.

In the Files header:

A check mark beside a file's icon shows that the machine has already plotted it. Hidden files, whose names start with a period, and the system folders System Volume Information and $RECYCLE.BIN are not listed.

Click a file to select it. Shift-click selects a range of files, and ⌘-click (Ctrl-click on Windows) selects or deselects a single item. Right-click a file for Begin Plot or Delete; right-click a folder for Delete Folder.

Click a folder to open it. Inside a folder, its path, such as SD / Samples, appears above the list; click SD, or any folder in the path, to go back up.

The Files list inside a folder, with its path above
The Files list inside a folder, with its path above

Along the bottom of the file list:

While a job is plotting, Home, Upload File, Begin Selected, the trash-icon button, the right-click Delete and Delete Folder items, and the refresh button are unavailable. Queue Selected and Queue Unplotted stay available, so you can add files to the queue while the machine plots.

A note above the file list reports on the listing itself, and shows nothing while the list on screen is current. It reads:

Files section inside a folder, showing the last file list after a refresh could not complete
Files section inside a folder, showing the last file list after a refresh could not complete

If no machine is connected, this area reads Connect to a plotter to manage files.

Note

Completed plots stay on the machine, so you can review or re-plot them from the MACHINE tab without removing the microSD card.

Right-click menu for a file in the Files list
Right-click menu for a file in the Files list

16.7 Uploading a generated job #

There are a few ways to get a job onto a connected machine:

Once you choose a file, Upload File opens a USB File Upload or WiFi File Upload dialog, using the connection set by Preferred connection for uploads (see §17.3.5 Preferred connection for uploads). The dialog shows the file's name, a message such as Uploading file..., and a progress bar with a percentage. Its Cancel button stops the upload. During a USB upload the button reads Cancel / Disconnect, since stopping a USB transfer also disconnects the machine. When a G-Code file finishes uploading, the dialog reads Upload complete. and offers Plot Now, which starts the file right away, and Close. Other files close the dialog with an "Upload complete" message. If the upload could not be verified, the dialog says so. See §17.3.4 Offer to plot after upload.

USB File Upload dialog partway through an upload
USB File Upload dialog partway through an upload

A WiFi upload option is available when the machine is reachable over WiFi. USB upload stays available without an active connection: the queue holds the job and sends it once the machine is connected, which Auto-connect over USB (on by default) does as soon as the machine comes online. Both depend on Show Machine Control Tab; with it off, Studio does not look for a machine at all.

16.8 The queue #

The QUEUE sub-tab, headed STUDIO QUEUE, tracks every job Studio is generating, uploading, or waiting to plot — jobs you've queued yourself and jobs Studio received automatically. A Clear All Failed button appears whenever there are failed jobs to clean up.

Just below the header is the Auto Start Plot toggle. When on, Setup Sheet and queue uploads that finish and are verified start plotting automatically, and so do files queued from the machine's microSD card. When off, they wait on the plotter until you press Plot. (Default: off) Upload File never starts a plot on its own; its dialog offers Plot Now instead. An upload that finishes as On plotter — not verified waits for you to press Plot. The line beneath the toggle is a reminder of that: Applies to Setup Sheet and queue uploads, not Upload File.

When one or more jobs are ready to upload, Upload All Ready via USB and Upload All Ready via WiFi buttons appear so you can send every ready job over a connection at once instead of one at a time.

16.8.1 Job rows #

If the queue is empty, it reads No jobs queued. Send work from Studio to start. Otherwise, the active job appears first, followed by any pending jobs, then a FAILED section for jobs that need attention.

Each row shows the job's name and its status:

Active job plotting, with Pause on its row
Active job plotting, with Pause on its row

Depending on a row's state, you may see:

A failed row says why beneath the job name, and what to check before you try again. Studio never sends a plot to the machine a second time on its own. When it cannot confirm that a plot started, the row reads Could not confirm whether this plot ran. Check the plotter and the card before retrying. Look at the sheet before you click Retry, so the same page is not plotted twice.

If you quit Studio while a job is plotting, Studio does not plot it again when you reopen it. The row is checked against the machine when Studio reconnects, and if the outcome is unclear, it asks you to check the sheet before retrying.

When the machine pauses for a pen or tool change, the active row shows the machine's instruction in orange beneath the job name, marked with a pen glyph. Make the change, then click Resume.

Active job paused for a pen change, with its instruction beneath the row
Active job paused for a pen change, with its instruction beneath the row

A hint below the active and pending rows reminds you: Completed plots stay on the plotter — view or re-plot them from the Control tab.

QUEUE sub-tab with two jobs reading On plotter — press Plot to start
QUEUE sub-tab with two jobs reading On plotter — press Plot to start

16.8.2 Queue warnings #

An orange, outlined banner can appear at the top of the MACHINE tab — above both the CONTROLS and QUEUE sub-tabs — whenever the queue hits a condition that needs your attention: a full queue, an unusually large backlog, jobs waiting on a machine connection, or saved jobs that couldn't be restored. Resolve the condition it describes — connect a machine, clear some jobs, and so on — and the banner clears on its own.

17. The SETTINGS tab #

The SETTINGS tab holds global Bantam Tools Studio™ preferences, machine limits, machine-control preferences, help links, downloads, support links, and license tools. Studio keeps its settings between sessions, and most you set once and rarely revisit. This chapter documents each of them, in the order the tab presents them.

The SETTINGS tab
The SETTINGS tab

The SETTINGS tab is organized into several areas:

17.1 Program options #

The PROGRAM OPTIONS section holds general Studio behavior settings.

PROGRAM OPTIONS with the Text Add-On
PROGRAM OPTIONS with the Text Add-On

17.1.1 Display Units #

Display Units toggles Studio between inches and millimeters. (Default: Inches) On EggBot, the only unit is degrees.

Pressing ⌘U (Ctrl+U on Windows) switches units at any time.

17.1.2 Merge File Naming #

Merge File Naming sets how Studio names the files a Data Merge produces, so that you can tell which document came from which row of the CSV file. Data Merge is part of the Bantam Tools Studio Text Add-On, and this setting appears only when your license includes text features.

The Merge File Naming menu
The Merge File Naming menu

The setting changes only the suffix Studio adds to each file name, not where the files are saved. For the full naming rules, including page suffixes and what happens when no data is substituted, see §11.7 Output file names.

17.1.3 Fit To Margins Also Centers #

Fit To Margins Also Centers centers the artwork after fitting it to the available margin area. (Default: off)

17.1.4 Fit To Margins On Load #

Fit To Margins On Load scales newly opened artwork to fit within the available margin area. (Default: off)

17.1.5 Center On Load #

Center On Load centers newly opened artwork in the available work area. (Default: off)

17.1.6 Illustrator Scaling #

Some Adobe Illustrator files do not correctly encode the document size, and open in Studio at three-quarters of their intended size. Illustrator Scaling sets when Studio corrects those files automatically as they open.

  • None — corrects nothing automatically. Any open document can still be corrected by hand; see §12.1 Opening files and file actions. (Default)
  • When identified — corrects files that identify themselves as Illustrator exports.
  • All px documents — also corrects files that carry no such identification. This can misscale correctly sized files from other programs, so it suits a workflow that is almost entirely Illustrator files.
Illustrator Scaling menu open
Illustrator Scaling menu open

When Studio corrects a file as it opens, a notification says so and names this setting, where the automatic correction can be turned off. Opening several files at once gives one notification, with a count.

Notification after Studio corrects a file as it opens
Notification after Studio corrects a file as it opens

To keep a file at its intended size from the start, set up the Illustrator document in physical units such as inches or millimeters, and export it with File → Export → Export As rather than Save As: choose the SVG format, check Use Artboards, and under Styling choose Presentation Attributes.

Hover help for the Illustrator Scaling setting
Hover help for the Illustrator Scaling setting

17.1.7 Opening text files opens Text tab #

Opening text files opens Text tab switches Studio to the TEXT tab whenever you open a supported text file. (Default: on)

The supported text files are .txt and .rtf files.

17.1.8 Auto assign on Toolset change #

Auto assign on Toolset change updates tool assignments when you switch toolsets. (Default: off)

Switching from one pen toolset to another, for instance, maps the detected colors to the default tools in the new toolset, apart from rows you have set to None; skip this task or hidden.

17.1.9 Use the saved toolset in Prepare #

Use the saved toolset in Prepare also selects a toolset on the PREPARE tab when you save it in the Tool Library. (Default: off) Checking Use this toolset in Prepare in the save confirmation turns this on.

17.1.10 Precision #

Precision controls how closely generated paths follow the source geometry. (Default: 0.05 mm)

A smaller value preserves more detail, at the cost of larger files and longer processing. A larger value simplifies and smooths paths and processes faster, at the cost of detail.

17.1.11 Pre-generate next queued job #

Pre-generate next queued job lets Studio prepare the next queued job in advance. (Default: on)

This helps automated or high-volume queues move more smoothly.

17.1.12 Enable Plob output #

Enable Plob output adds a Save as Plob option to Studio. (Default: off)

Plob, short for "Plot Object," is a highly specialized kind of SVG file, processed in advance for fast plotting workflows. Turning this setting on reveals a Plob sub-group with two additional options:

PROGRAM OPTIONS with Enable Plob output on, showing the Plob rows
PROGRAM OPTIONS with Enable Plob output on, showing the Plob rows

The Plob: Model menu
The Plob: Model menu

For more about Plob and how to export one, see §11. Exporting output.

17.1.13 Include support info in project files #

Include support info in project files saves a small, redacted diagnostic record inside every project file, so Bantam Tools support can diagnose a problem from a project file you send. (Default: on) The record holds app and system versions, recent activity, and recent log lines; passwords, Wi-Fi network names, and your user name are removed. Projects you save after turning it off don't carry the record. See §11.4 Project files.

17.2 Machine options #

The MACHINE OPTIONS section holds machine-specific limits.

17.2.1 Maximum Media Size #

Maximum Media Size defines the maximum X and Y work area for the selected machine.

It keeps Studio from generating output beyond the safe drawing area, so a job that would run past the edge is caught before it reaches the machine. It does not change the document size or the margins; those live on the PREPARE tab.

Change these values for a custom machine or a special setup.

Maximum Media Size fields
Maximum Media Size fields

17.3 Machine control #

The MACHINE CONTROL section holds the settings for connecting to a machine and uploading files to it.

The MACHINE CONTROL settings
The MACHINE CONTROL settings

17.3.1 Show Machine Control Tab #

Show Machine Control Tab shows or hides the MACHINE tab, where you connect to a machine, control it directly, browse the files stored on it, and manage the upload queue. (Default: off) §16. The MACHINE tab covers the tab itself.

The setting governs more than the tab. With it off, the actions that send a job straight to a machine are unavailable as well: Generate G-Code and Upload on the File menu is grayed out, and the Setup Sheet omits its upload actions. Moving G-Code to your machine on a microSD card needs none of this, so the setting can stay off.

Turn this setting on once your machine is up and running from the microSD card. A USB or WiFi connection then adds convenience to a machine you already know works. Studio gives the same advice the first time you turn the setting on, in a dialog titled Plotter Control is Early Access.

The advice Studio shows the first time you turn on Show Machine Control Tab
The advice Studio shows the first time you turn on Show Machine Control Tab

17.3.2 Auto-connect over USB #

Auto-connect over USB has Studio connect to a machine over USB as soon as one is detected. (Default: on)

With it off, connecting is a deliberate act: the Connect button on the MACHINE tab.

17.3.3 Verify uploads with checksum #

Verify uploads with checksum has Studio confirm, after each upload over USB, that the file on the machine matches the file Studio sent. (Default: off) Uploads over WiFi are always checked against the size Studio sent, whether or not this is on.

It adds a brief verification step after each USB upload completes.

17.3.4 Offer to plot after upload #

Offer to plot after upload keeps the upload dialog open when a G-Code file finishes uploading, with a Plot Now button. (Default: on) With it off, the dialog closes with an "Upload complete" message. Checking Don't show this again in the dialog turns this off.

17.3.5 Preferred connection for uploads #

Preferred connection for uploads sets which connection Upload File and Generate G-Code and Upload use:

The Preferred connection for uploads menu
The Preferred connection for uploads menu

If that connection isn't available, Studio uses the other one and says so, as in Upload falling back to USB — plotter unreachable on WiFi. For connection and upload workflows, see §16. The MACHINE tab.

17.4 Help and reference #

The HELP & REFERENCE section links to built-in help, documentation, downloads, tools, and support resources.

HELP & REFERENCE buttons
HELP & REFERENCE buttons

17.4.1 Keyboard Shortcuts #

Keyboard Shortcuts shows common keyboard shortcuts for Studio. The same list, with the macOS and Windows forms side by side, is in §18.1 Keyboard shortcuts.

Keyboard Shortcuts window
Keyboard Shortcuts window

17.4.2 About Project Files #

About Project Files explains what a project file (.btsp) holds, the support information saved inside it, and how to turn that off. See §11.4 Project files.

About Project Files window
About Project Files window

17.4.3 Toolset Descriptions #

Toolset Descriptions provides reference information about the included toolsets.

Preset Toolset Template Descriptions window
Preset Toolset Template Descriptions window

17.5 Downloads #

The DOWNLOADS section links to documentation and software resources. Each label ends in ↗ because the link opens a web page in your browser.

The links are:

  • Studio User Guide ↗ — this guide.
  • The user guide for the machine currently selected: ArtFrame User Guide ↗, EggBot User Guide ↗, WaterColorBot User Guide ↗, or plain User Guide ↗ for HandWriter.
  • The documentation page for the machine currently selected: ArtFrame Documentation ↗, EggBot Documentation ↗, WaterColorBot Documentation ↗, or plain Documentation ↗ for HandWriter.
  • Latest Firmware ↗
  • Download Latest Software ↗
DOWNLOADS links on ArtFrame
DOWNLOADS links on ArtFrame

These links reach the current documentation, the current firmware, and the latest Studio download.

17.6 Tools #

The TOOLS section links to related Bantam Tools utilities.

17.6.1 Image Processor #

Image Processor opens the Bantam Tools Image Processor™ in its own window. It converts a photograph or other raster image into an SVG file of strokes, ready to draw or paint. With no image loaded yet, the window opens with a sample image. See §9. The Image Processor.

17.7 Support #

The SUPPORT section links to the routes for getting help.

The links are:

  • Support Chat ↗ — the Bantam Tools community chat (bantam.tools/chat).
  • Contact Support ↗ — the Bantam Tools support site (bantamtools.com/support).
  • Save Support Bundle... — saves a diagnostic bundle to send to support (⇧⌘D / Ctrl+Shift+D).
TOOLS and SUPPORT sections
TOOLS and SUPPORT sections

Please use these links for help with installation, licensing, machine setup, connection issues, or output quality.

17.8 Bottom controls #

The bottom of the SETTINGS tab holds additional global controls.

Bottom controls of the SETTINGS tab
Bottom controls of the SETTINGS tab

17.8.1 Reset All Settings #

RESET ALL SETTINGS restores Studio settings to their defaults: program options, path generation options, layout, and machine settings, which take the defaults for the machine currently selected. Your Tool Library is not affected. Studio asks you to confirm before it resets anything.

It is the way back to a clean configuration when preferences have drifted into a confusing state.

Holding Option (Mac) or Alt (Windows) while clicking RESET ALL SETTINGS performs a factory reset, which returns Studio to its on-install state. It clears everything Studio stores except your license activation:

Studio then restarts to the machine-selection splash screen.

Important note

A factory reset cannot be undone. Export any custom toolsets you want to keep before you use it; see §14. The Tool Library.

17.8.2 Reload Tool Presets #

RELOAD TOOL PRESETS reloads the factory tool presets, and leaves your own tools and toolsets alone. Use it to return the built-in presets to their factory values.

17.8.3 Check for Updates #

CHECK FOR UPDATES checks online for the latest version of Studio and opens the Update Bantam Tools Studio window. The window shows Your version and, when a newer version is available, Newest version along with links to its release notes and its download.

Below that, the Plotter Firmware section shows Latest firmware, the newest machine firmware this version of Studio knows of, and Your plotter, the firmware version of the machine you are connected to, marked (via USB) or (via WiFi). With no machine connected, it reads Connect a plotter to see its firmware version. When the connected machine's firmware is older than the latest, the section adds Firmware update available, with a link to the firmware download page (bantam.tools/fw).

Studio also checks once shortly after it starts, and opens this window on its own when a newer version is available.

17.8.4 About #

ABOUT shows version and application information.

About Bantam Tools Studio window
About Bantam Tools Studio window

17.8.5 License Manager #

LICENSE MANAGER opens the license tools for activating, deactivating, or checking your Studio license.

It is where a new computer is activated, and where access to licensed features is managed.

License Manager window with an active license
License Manager window with an active license

18. Keyboard shortcuts and dimension entry #

This chapter collects Studio's keyboard shortcuts and the rules for entering dimensions.

18.1 Keyboard shortcuts #

These are Studio's keyboard shortcuts and mouse gestures. The Keyboard Shortcuts window lists most of them:

SETTINGS → HELP & REFERENCE → Keyboard Shortcuts

The Keyboard Shortcuts window
The Keyboard Shortcuts window

On macOS, ⇧ is Shift, ⌥ is Option, and ↩ is Return.

18.1.1 File #

Action macOS Windows
Open File ⌘O Ctrl+O
Open from Clipboard ⇧⌘V Ctrl+Shift+V
Open Project ⇧⌘O Ctrl+Shift+O
Save Project ⌘S Ctrl+S
Save Project As ⇧⌘S Ctrl+Shift+S

See §12.1 Opening files and file actions, §3.6.2 Pasting from the clipboard, and §11.4 Project files.

Action macOS Windows
Switch to the PREPARE tab ⌘1 Ctrl+1
Switch to the TEXT tab ⌘2 Ctrl+2
Switch to the TOOLS tab (Tool Library) ⌘3 Ctrl+3
Switch to the MACHINE tab ⌘4 Ctrl+4
Switch to the SETTINGS tab ⌘5 Ctrl+5

The MACHINE tab shortcut works only when the tab is shown. See §3.2 The five tabs.

18.1.3 Actions #

Action macOS Windows
Save G-Code File ⌘↩ Ctrl+Enter
Open License Manager ⇧⌘L Ctrl+Shift+L
Undo a layout change ⌘Z Ctrl+Z
Redo a layout change ⇧⌘Z Ctrl+Shift+Z or Ctrl+Y

See §12.13 The PROCESS AND SAVE button.

18.1.4 View #

Action macOS Windows
Toggle full-screen mode ⌘F Ctrl+F
Toggle units (millimeters/inches) ⌘U Ctrl+U
Dock the Preview window ⌘W Ctrl+W

Docking applies when the Preview is open in a separate window, and that window is the one in front. See §3.3 The menu bar and §17.1 Program options.

18.1.5 Preview shortcuts #

Action macOS Windows
Fit to view ⌘0 Ctrl+0
Actual size (1:1) ⌥⌘1 Ctrl+Alt+1
Zoom in ⌘+ or ⌘= Ctrl+Plus (+) or Ctrl+=
Zoom out ⌘- Ctrl+Minus (-)
Pan view Arrow keys Arrow keys
Pan view five times faster ⇧ with arrow keys Shift with arrow keys

These shortcuts act on the Preview only after you click in it. See §12.12 Preview.

18.1.6 Mouse and trackpad #

Action macOS Windows
Pan view Scroll, two-finger swipe, or middle-button drag Scroll, two-finger swipe, or middle-button drag
Zoom at the cursor Hold ⌘ and scroll Hold Ctrl and scroll
Zoom in or out Trackpad pinch Trackpad pinch
Move the artwork Drag the artwork Drag the artwork
Adjust a margin Drag the margin edge Drag the margin edge

18.2 Dimension entry reference #

The dimension fields on the PREPARE tab and the palette offsets in Tool Settings evaluate arithmetic with unit suffixes. §12.5 Artwork settings explains the rules. The tables below list the units each kind of field accepts, worked examples, and the syntax errors Studio reports.

Field type Accepted units Bare number means
Length (margins, offsets, width, height) mm, cm, in, ft, pt The unit shown in the box
Percent (Scale) % Percent
Degrees (EggBot only) °, deg Degrees

Results below are for a length field displaying millimeters unless noted.

Typed Result
8 1/2 8.5 mm
1 in 25.4 mm
2.54 cm 25.4 mm
1 ft 304.8 mm
72 pt 25.4 mm
4/3 in 33.867 mm
6 in + 3 mm 155.4 mm
10 / 2 mm 5 mm
10 mm / 2 5 mm
(2 + 3) * 10 50 mm
8 1/2 in 215.9 mm
1/16, field displaying inches 0.0625 in
25.4 mm, field displaying inches 1 in
4/3, percent field 1.333%
(4/3) * 100%, percent field 133.33%
45 + 45, degrees field 90°

You can use either a period or a comma as your decimal point, as is common in many regions: 1.5 and 1,5 both enter 1.5. Because a comma is always read as a decimal point, it never separates thousands, so 1,000 means 1. To enter one thousand, type 1000.

Studio checks each entry as you type and reports what it could not read. The entries below are the ones that come up most often, with the message shown and what to type instead.

Typed Message Type this instead
1/8in Syntax: Don't divide by a unit 1/8 in — put a space before the unit, so the unit applies to the whole fraction
2 in * 3 in That value already has a unit. 2 * 3 in — give the unit once; this evaluates to 6 in (152.4 mm)
10 km This field does not accept the unit "km". Use mm, cm, in, ft, or pt
10 mm in a percent or degrees field This field does not accept the unit "mm". Percent fields take % or a bare number; degrees fields take ° or deg
5 ft 6 in Unexpected input after the expression. 5 ft + 6 in — join the two with +
abc A unit needs a number before it. Enter a number, optionally followed by a unit
1/0 Division by zero. Use a nonzero divisor — the expression has no value as written

A value outside the field's allowed range is rejected with "Value is out of range."

Part IV: Appendices

19. Troubleshooting #

This chapter provides reference solutions to common problems, grouped by area: SVG import, text and fonts, Data Merge, the Image Processor, plot quality, machines, connections, and project files.

19.1 SVG import problems #

Issue: SVG does not appear correctly in the Preview.
Solution: Check that the SVG uses standard formatting. Export as Plain SVG if available.

Issue: Text or artwork in the SVG file is missing from the Preview.
Solution: Check whether it sits on a documentation layer, one whose name begins with %; Studio leaves those layers out. See §20.8 Guides and documentation layers.

Issue: Elements are missing from the imported SVG.
Solution: Ensure elements are converted to paths or properly grouped before export.

Issue: Text from an SVG does not plot as expected.
Solution: Convert text to paths in your design software before importing, unless you are using the text rendering features built into Bantam Tools Studio™.

Issue: A page reports This page failed to render above the page navigator.
Solution: Studio could not draw the page, and the message stays until the page is rendered again. Reload the file, or open it in the program that produced it and confirm that it is valid. To reload it, use the chevron menu beside Open File:

Open File → Reload file from disk

Issue: A page reports No plottable content on this page above the page navigator.
Solution: The page rendered successfully but holds no strokes a pen could draw; an SVG file whose content is entirely raster images is the usual cause. The page still generates an output file, and that file has no motion in it. See §12.13.1 Empty pages in a batch.

Issue: Artwork from Adobe Illustrator opens at three-quarters of its intended size.
Solution: Some Adobe Illustrator files do not correctly encode the document size. Restore the intended size from the chevron menu beside Open File:

Open File → Rescale Illustrator SVG

§17.1.6 Illustrator Scaling describes correcting such files automatically as they open, and exporting from Illustrator so that the problem does not arise.

19.2 Text and fonts #

Issue: Text does not fit.
Solution: Reduce the text size, adjust the margins or the layout, or use the spacing and overflow controls. See §6.6 Font size, spacing, and overflow.

Issue: Text wraps differently than expected.
Solution: Check the text area size, font choice, spacing, overflow behavior, and margins. See §6.6 Font size, spacing, and overflow.

Issue: A font is unavailable.
Solution: The full font library requires the Bantam Tools Studio Text Add-On; confirm that it is active in the License Manager.

Issue: PROCESS AND SAVE reads Font issue, and the job does not generate.
Solution: The font selected for this job can't be found, as when a project names a font that isn't on this computer. The Preview reads Font not available and names the font. Choose a different font with Font face, or add the font with Additional font. See §6.4 Font selection.

Issue: The HANDWRITING DEFECTS section is grayed out.
Solution: Handwriting Defects is part of the Bantam Tools Studio Text Add-On; confirm that it is active in the License Manager. See §13. The TEXT tab.

Issue: A signature does not appear in a letter.
Solution: Check that the signature command is written exactly as {{sig}}, {{sigalt}}, or {{siginit}}. For {{sig}}, open the SIGNATURE section and confirm a signature file is loaded, or that the font includes a signature. See §13.4 Signatures.

Issue: PROCESS AND SAVE reads Signature issue, and the job does not generate.
Solution: A font in the document cannot supply what a signature command asks for. The CSV DATA PREVIEW section, on the DATA MERGE sub-tab of the TEXT tab, names the command and the font; the section appears for this even when Data Merge is off. Choose a font that includes it, load a signature file (for {{sig}}), or remove the command. See §13.4 Signatures.

Issue: Studio reports Text layout error: each document is limited to 100 pages.
Solution: Shorten the text or reduce the font size to bring the document under 100 pages. If your work needs longer documents, please contact support at support@bantamtools.com so that we can hear about your use case.

19.3 Data Merge problems #

Issue: The DATA MERGE sub-tab is grayed out.
Solution: Data Merge is part of the Bantam Tools Studio Text Add-On; confirm that it is active in the License Manager. See §7. Data Merge.

Issue: Merge fields appear in the Preview instead of the data.
Solution: Confirm that a CSV file is selected beside CSV data file and that Preview merge result is on, since the Preview area otherwise shows the raw merge fields rather than the data. The CSV DATA PREVIEW section reports how many rows, columns, and merge fields Studio found. See §7. Data Merge.

Issue: A field comes out empty in one document while the others are correct.
Solution: Check that row's cell in the CSV file. An empty cell produces an empty field, and any punctuation or spacing you wrote around the merge field goes with it. Use conditional text if the field is optional, so the line only appears when there is something to write. See §7. Data Merge.

Issue: Studio refuses to generate and reports a missing column.
Solution: The merge field names a column the CSV does not have. Matching ignores letter case and surrounding spaces, so a mismatch means the header text itself differs — for example, address2 versus address 2. Correct the header or the merge field; Studio will not generate a batch whose fields it cannot fill.

Issue: Studio reports a "CSV file problem" when you choose a CSV file.
Solution: Studio could not read the file's columns. The file needs at least two columns; if yours has only one, add a second column that numbers the rows. If the message says the columns could not be read consistently, save the file again from your spreadsheet application as a comma-separated file. See §7.2 CSV files and merge fields.

Issue: Address blocks have extra blank lines.
Solution: Use conditional text with \r so optional lines only appear when the field has data.

Issue: The wrong row appears in a label, card, or envelope.
Solution: Check ++ offsets, {{nextrow}} placement, and processing order. See §7.4 Referencing future rows.

Issue: The merge skips the last few CSV rows.
Solution: Confirm that the remaining rows are enough to fill the full generated page. A merge that uses three rows per page needs rows in groups of three.

Issue: One merged document runs to far more pages than the rest.
Solution: Check that row's data for a field holding more text than the template expects, and check the Page breaks setting: Break at paragraphs spends pages to keep paragraphs whole. See §6.7.1 Page breaks.

Issue: A generated batch has unexpected names.
Solution: Choose the Merge File Naming mode before generating rather than after, since renaming a folder of finished files is far more work. See §11.7 Output file names.

Issue: A Data Merge builds only the first 250 documents.
Solution: A batch holds up to 250 documents, and the CSV DATA PREVIEW summary reads "250 documents (limited to 250)" when a row range asks for more. Run the rest as a second batch by setting Start row past the last row of the first. If your work needs larger batches, please contact support at support@bantamtools.com so that we can hear about your use case.

19.4 Image Processor problems #

Issue: An image opened in the Image Processor reports Image Load Failed with "Image file too large."
Solution: The Image Processor refuses files larger than 50 MB. Save a smaller copy of the image, such as a JPEG no more than 4,096 pixels on its longest side, which loses nothing at the resolution the Image Processor works at. See §9.2 Opening the Image Processor.

Issue: The result looks blocky, or small details are missing.
Solution: The Image Processor works at about one pixel per millimeter of printable area, and each stroke is a full brush width, so detail finer than the brush is lost. Use a narrower Stroke Width, a larger paper size, or an image whose subject fills the frame. See §9.1 What the Image Processor does.

Issue: Changing a setting does not change the preview.
Solution: Check that Auto Refresh is on, or click Process Image. See §9.4 The Image Processor window.

Issue: Saving from the Image Processor reports "Failed to open file for writing."
Solution: The folder the Save SVG dialog suggested cannot be written to, which can happen with the sample image. Choose a folder such as Documents or Downloads. See §9.11 Saving the artwork.

Issue: The painting takes far longer than expected.
Solution: Image Processor artwork can hold many thousands of strokes. Check the estimated time on the Setup Sheet, and for a quicker painting use a wider brush, a smaller paper size, Paint Stripes, or fewer Fill passes in Paint Shades. See §9.12 Painting Image Processor artwork.

19.5 Plot quality problems #

Issue: Lines are too light or inconsistent.
Solution: Increase Draw Depth slightly (Pressure Depth on HandWriter) or reduce speed.

Issue: Lines are too heavy or the pen catches.
Solution: Decrease Draw Depth (Pressure Depth on HandWriter) or reduce plotting speed.

Issue: Curves appear jagged.
Solution: Make sure Use Curves is enabled (it is always off on EggBot) and adjust Precision.

Issue: Pen drags during travel moves.
Solution: Increase Pen Up Height.

19.6 Machine problems #

Issue: Machine will not home correctly.
Solution: Check that all movement areas are clear and nothing is blocking the rails or moving parts. The user guide for your machine lists what else to check for that machine. If a queued job's row reads Homing failed (ALARM:n)…, nothing was plotted: click Clear Alarm on the row, check that nothing is in the way, then click Retry.

Issue: Plotter starts but pauses unexpectedly.
Solution: Check that the G-Code file is complete and that the microSD card is properly formatted. Note that a brief pause partway through a multi-tool job is normal — Studio shows the pen or tool-change instruction and a Resume button; see §16.5 Machine controls.

19.7 Connection problems #

A connection problem shows a code with a short description, such as BT-302 — USB connection lost. Codes from 100 to 399 concern USB, and codes in the 500s and 600s concern WiFi. Most messages appear briefly and clear on their own. Five stay beneath the connection row on the MACHINE tab, with Try Again and Copy Diagnostics buttons:

For USB issues:

For WiFi issues:

When a problem involves sending files to the machine or controlling it from Studio, consider switching to the microSD card, or, if you are using WiFi, to USB. Each removes one link between your computer and the machine, which helps show where the problem lies. For trouble with the WiFi connection itself, work through the WiFi steps above.

For support, click Copy Diagnostics when it's available, or note the BT-<code> shown in the toast, and include it in your message.

19.8 Project file problems #

Issue: Studio reports that a project requires a newer version.
Solution: A project saved by a newer version of Studio can use features that the version you are running does not have, and Studio reports "This project requires Bantam Tools Studio X or later," naming the version that saved it. Visit bantam.tools/sd to download the latest version, or use Download Latest Software on the SETTINGS tab.

Issue: Studio reports "Another operation is in progress."
Solution: Studio saves or opens one project at a time. Wait for the current save or load to finish, then try again.

Issue: Studio reports "Project file is corrupted."
Solution: Studio could not read the file as a project: it is missing, unreadable, or not a valid project file. Check that the file is where you expect and finished copying or downloading, then try again with a fresh copy.

Issue: Saving a project reports "Missing source file."
Solution: A document you have open can no longer be found where Studio opened it from, so Studio can't include it in the project. Put the file back where it was, or open it again from its new location, then save the project.

Issue: Studio reports "Some files failed to load."
Solution: The rest of the project opened. The documents that couldn't be loaded appear as placeholders, and the message lists which ones.

Issue: Studio reports "The project was not opened."
Solution: None of the project's documents could be read, so nothing changed: your open document and settings stay as they were. Try again with a fresh copy of the project file.

19.9 Getting help #

If you encounter an issue not covered here, use the support resources listed in §0. Preliminaries.

Diagnostic information from Studio, which includes none of your documents, can help us find the cause. Studio offers it two ways: Copy Diagnostics, beside a connection error on the MACHINE tab, copies a short version to paste into your message; Save Support Bundle on the SETTINGS tab (⇧⌘D / Ctrl+Shift+D) saves a fuller version as a file to attach, at any time.

If you're comfortable sharing it, your project file (.btsp) holds your documents and settings along with the same diagnostic information; see §11.4 Project files. Project files don't include exported G-Code, so if the problem happens while running a G-Code file, such as from the microSD card, send that file as well.

20. Appendix: SVG templates in Inkscape #

Read this appendix before designing a template in Inkscape or another vector editor.

20.1 Deciding whether you need a template #

An SVG template is a reusable page layout — fixed artwork, branding, and text areas already in position — that you build in a vector editor and then open in Bantam Tools Studio™. Studio is not a design tool, so a template is how a designed page reaches it.

Most documents do not need one. Opening a .txt or .rtf file with OPEN FILE, or bringing copied text in with Open from Clipboard, is the fastest way to write a page: you bring the text in, choose a handwriting font, and use the PREPARE tab to lay the document out with margins, FIT TO MARGINS, CENTER, scale, offsets, overflow behavior, and manual dragging in the Preview. When the text is a single block on the page, as it is in most notes and letters, this is an excellent workflow. If that describes your document, you can skip this appendix and go to §6. Writing text instead.

The short version of the distinction: use a text document when you are composing, and use a template when you are designing a finished page. A template moves the layout decisions ahead of Studio — you choose where the text sits, where the artwork goes, and how the page is structured — which is more control and, in exchange, more preparation.

Reach for a template when any of these is true:

Opening a template whose text is already in place needs no additional purchase. What the Bantam Tools Studio Text Add-On adds here is Data Merge — putting merge fields such as {{first_name}} in the template and producing a batch of personalized documents from a CSV file. See §7. Data Merge.

20.2 Choosing an editor #

We recommend Inkscape. It is free to use, it runs on macOS, Windows, and Linux, and its text tools, simple as they are, match the kind of text formatting that works well in a Data Merge template. Adobe Illustrator and other vector editors work too.

20.3 Setting the document size #

Set the document size before you design the layout, so the page in your editor matches the page you will write on. Positioning text, logos, and signatures against the wrong page size is work you will do twice.

In Inkscape, open the template chooser and pick the paper size that matches your intended output:

File → New from Template

New from Template on Inkscape's File menu
New from Template on Inkscape's File menu

Use a document size that matches your intended paper, material, or work area.

Leave enough margin around the design for the machine to feed and write safely. Keep important text, artwork, borders, and signatures clear of the page edges.

Tip

In Inkscape, View → Zoom → Zoom Page fits the whole page in the window while you work.

20.4 Creating text areas #

Text areas are made with Inkscape's Text tool. Click the Text tool icon in the toolbar, press T, or press F8; when the tool is active, the cursor changes from an arrow to a text-entry cursor. A text area created this way can hold ordinary text, merge fields, or both.

Inkscape makes two kinds, and the difference is simply this: flowed text wraps onto the next line by itself when a line gets too long, and regular text does not. Flowed text suits anything made of sentences, and anything you want to be certain will not run off the edge of the sheet. Regular text suits anything whose shape you are setting yourself.

20.4.1 Flowed text #

Flowed text wraps inside a rectangle you define, so a line that grows too long moves to the next line. With the Text tool active, click and drag on the page to draw the rectangle, release, and type or paste the text into it. Selecting the area with the Text tool lets you drag its resize handle or move it anywhere on the page.

Use flowed text for document bodies, paragraphs, notes, and anything else that should wrap inside a defined area. Its real value is control of paragraph width, which keeps body copy from running the full width of the sheet.

A flowed text area just after the drag: the blue outline, the diamond resize handle at its lower right, and the cursor ready to type
A flowed text area just after the drag: the blue outline, the diamond resize handle at its lower right, and the cursor ready to type

Text typed into that area wraps at the edge of the box
Text typed into that area wraps at the edge of the box

20.4.2 Regular text #

Regular text does not wrap. Select the Text tool, click once on the page, and type; the line continues until you add a return yourself.

Use regular text for names, dates, labels, short headings, address lines, fixed text blocks, and single-line merge fields. A certificate template is the clear case: the recipient's name belongs in one specific spot on the page, not inside a wrapping box.

Regular text runs on until you type a return yourself
Regular text runs on until you type a return yourself

20.4.3 Which one reflows #

Studio writes in a stroke font rather than the font your editor used, so flowed text wraps in different places than it did in Inkscape, exactly as it would if you changed the font there. A paragraph may run to a different number of lines.

Regular text does not move: its line breaks are the ones you typed, so an address block keeps the shape you gave it. That is another reason to reach for regular text where the arrangement matters and flowed text where the wrapping should look after itself.

Leave a little room in a flowed area rather than fitting text to the millimeter, and use the Preview to see where the lines actually fall.

20.4.4 Multiple text areas #

A template may hold as many text areas as the layout needs, each positioned independently and each holding fixed text, merge fields, or both. A letter might carry a recipient address block, a greeting, a body area, a donation amount line, a signature line, and a return address or footer.

Separate areas help most when one part of the page needs its own placement, such as an address block positioned for a window envelope, and when the page repeats one item, such as a sheet of labels or several envelopes side by side. To fill each repeated item from a different CSV row, see §7.4 Referencing future rows.

A layout that reads naturally as one block is simpler as one text area. Do not force a whole page into one large box when the layout would be easier to manage in pieces — and do not split a plain letter into six boxes because you can.

20.5 Adding merge fields #

If the template will be used with Data Merge, type the merge fields directly into the text areas, the same way you would in any other text field.

The first row of the CSV file holds the column headers, and those headers become the field names Studio matches against the merge fields. Keep the names short: first_name, last_name, address1, city, and zip are easier to troubleshoot than long spreadsheet headers.

20.6 Adding logos and graphics #

Carrying more than text is the main reason to use a template at all, and fixed SVG elements appear on every document generated from it:

These elements should be SVG paths or shapes that Studio can process as plottable motion. A raster image is not motion and will not be drawn, so convert anything of that kind to vector artwork first.

If a logo or graphic should be drawn with a particular pen, give it a distinct stroke color, layer, or group. That is what Studio lists for tool assignment when the file opens.

20.7 Keeping text editable #

Do not convert text to paths before opening the file in Studio. Editable text is what lets Studio recognize the text content and render it with a handwriting font; text already converted to paths behaves like ordinary artwork, and handwriting fonts, Data Merge, signatures, spacing controls, and Handwriting Defects no longer apply to it.

Tip

Save a master editable version before making production changes. A name like document_template_editable.svg makes it clear which file to come back to when the layout or the text needs work.

20.8 Guides and documentation layers #

A template often wants marks that are meant for you rather than for the pen:

Keep these separate from the artwork you intend to draw, on a layer of their own, and give that layer a name beginning with %. Studio treats such a layer as a documentation layer and leaves it out of everything it produces: it is not drawn, its text is not rendered, and a Data Merge does not fill merge fields inside it.

Name the layer in your editor — in Inkscape, rename it in the Layers panel, or edit its label in the XML editor. %Guides, %Notes, and %Fold lines all work; only the leading % matters.

Three documentation layers above an ordinary one, in Inkscape's Layers panel
Three documentation layers above an ordinary one, in Inkscape's Layers panel

A documentation layer can stay visible while you work, which is the point of it: you can see your safe area and fold lines on screen without hiding them each time you process the file, and without deleting work you will want again when you revise the template.

Color does the same job without renaming anything. Draw layout guides in a color the finished piece does not use, such as blue, and on the PREPARE tab, with Sort Strokes By set to Colors, assign that color to None; skip this task. A pen assigned only to black then never draws the blue guides.

Note

Everything on a documentation layer is left out of the output, including text or artwork placed there by mistake. If something you expect to see is missing from the Preview, check which layer it is on in your editor.

20.9 Saving the template #

Save the finished layout as an SVG. That file is your reusable template: reopen it later to update the text, adjust the layout, change the merge fields, or pair it with a different CSV file.

Keep the editable template apart from generated output. A workable project folder holds the editable .svg template, a test CSV, a production CSV, notes about paper, pens, margins, and tool assignments, and any generated G-Code files.

20.10 Opening the template in Studio #

Open Bantam Tools Studio, click OPEN FILE, and select the template. Studio reads the text and SVG elements from the file, and the template's text areas and artwork appear in the Preview as plottable paths.

From there, the TEXT tab sets fonts, spacing, Handwriting Defects, overflow behavior, signatures, and Data Merge options when they are available. The PREPARE tab is where you confirm machine selection, paper size, margins, artwork position, toolset, and tool assignments.

20.10.1 Assigning tools #

Studio detects the colors, layers, and groups in the file and lists them under TOOL ASSIGNMENTS. Each one gets a tool, which is how you decide what draws which part of the page: a black tool for the body text, blue for a signature, red for a decorative mark, a separate tool for a logo or border. If the whole template uses a single tool, assign that tool to every visible part.

Organizing the file by color, layer, or group before it reaches Studio makes this step much shorter, which is the practical reason to bother with layers in the editor.

TOOL ASSIGNMENTS for a template, with each color assigned a tool
TOOL ASSIGNMENTS for a template, with each color assigned a tool

20.10.2 Checking the Preview #

Review the Preview before generating anything. Confirm that what you intend to plot, write, or paint fits within the margins, that fixed artwork and text land where you expect, and that nothing meant as a guide is about to be drawn. The Preview draws anything outside the margins in red, and processing crops it.

If something sits too close to an edge, the fix is in the design file, not in Studio: adjust the layout there, save the SVG again, and reopen it.

For a Data Merge template, look through several records in the Preview, including the one with the longest content if length is a concern.

20.11 Generating and writing a template job #

With the Preview correct, generate the job the same way you would for any other document. Over USB or WiFi you can upload the file straight to the machine; for microSD, click PROCESS AND SAVE, save the file, and copy it to the card.

Load the tool and the media before starting the file, then start it from the machine's display or send it from Studio. The machine plots, writes, or paints the template with the loaded tool, or with each assigned one in turn.

21. Appendix: Stroke font samples #

These are the stroke fonts included with the Bantam Tools Studio™ Text Add-On, each writing the same two lines so the faces can be compared against one another. Choose one in the FONT section; see §6.4 Font selection.

The samples are drawn at a single size; each face looks somewhat different larger or smaller. Where to find more, and how to add your own, are in §6.4 Font selection as well.

BNTM Allure through BNTM Decorous Script
BNTM Allure through BNTM Decorous Script

BNTM Delight through BNTM Neato
BNTM Delight through BNTM Neato

BNTM Nixish through BNTM Society
BNTM Nixish through BNTM Society

BNTM Speculation through Hershey Script medium
BNTM Speculation through Hershey Script medium

The Hershey Serif faces
The Hershey Serif faces

Of the Hershey faces, Hershey Sans 1-stroke and Hershey Script 1-stroke are the two that every copy of Studio carries, with or without the Text Add-On.

22. Glossary #

Terms used throughout this guide.

Acceleration: How quickly the machine builds up to its target feedrate, and how quickly it slows again at the end of a move.

Alarm: A machine fault state that stops all motion until it is cleared. While the machine is in an alarm state, the MACHINE tab offers Clear Alarm: resolve whatever triggered the alarm, then clear it to return the machine to Idle.

ArtFrame™: A family of Bantam Tools machines for flat drawing and painting workflows, made in three sizes.

Bantam Tools HandWriter®: A Bantam Tools machine that writes on sheet paper with a pen, in sizes from US Letter and A4 up to US Legal.

Bantam Tools Studio™ Text Add-On: The part of Bantam Tools Studio™ that adds the full font library, custom SVG fonts, signatures, Handwriting Defects, letter and word spacing, overflow controls, clipboard and text-file import, and Data Merge. It is a separate purchase for Studio, and is included with every Bantam Tools HandWriter®; bantamtools.com/text has details.

Baseline (Text Add-On): The line the letters sit on. The Baseline jitter defect lets written lines drift slightly above and below it.

Batch: A set of documents open together. A file batch comes from opening several files at once; a merge batch is the set of documents Data Merge produces from one CSV file.

Centerline: The line running down the middle of a drawn stroke. Single-stroke fonts are built from centerlines, so the pen follows the middle of each letter rather than tracing its outline.

Chevron: The small arrow beside a button that opens a menu of related actions.

Conditional text (Text Add-On): Data Merge syntax, written in double square brackets inside a merge field, that changes what is written depending on whether a CSV cell holds a value.

Data Merge (Text Add-On): A feature that creates personalized documents from a CSV file, replacing each merge field with the value from that row.

Dip: Lowering the brush into one location on the palette. It is the basic action each stage of Tool Macro Setup performs, with a repeat count setting how many dips happen at each location.

Document: One unit of input content. Opening several files at once gives as many documents as files, and Data Merge produces one document per merged unit, the template plus its data; a document may run to one page or several.

Draw Depth: The distance the tool travels past the point of surface contact. It applies to tools using relative heights, and turning on Enable Absolute Z Positions replaces it with Pen Down Height.

EggBot™: A Bantam Tools machine for plotting on round and ovoid objects.

Feedrate: The speed at which the tool moves along a programmed path, set per tool in the Tool Library.

Fill: The SVG property that colors the inside of a shape. Studio processes artwork as though paths have a stroke and no fill, so a filled shape does not come out solid; the pen draws the outline it finds.

G-Code: A machine instruction language that tells a computerized tool how to move.

Handwriting Defects (Text Add-On): A group of controls that introduce measured natural imperfection into writing, so that it reads as handwritten rather than typeset.

Hershey Sans 1-stroke: A single-stroke sans-serif font included with Bantam Tools Studio™.

Hershey Script 1-stroke: A single-stroke script font included with Bantam Tools Studio™.

Hidden Line Removal: A processing option that draws only the paths that have a stroke and are not hidden behind filled objects, so overlapping artwork does not show lines that should be covered.

Home: The machine's starting place: a known reference position that every later move is measured from. As a verb, to move the machine there; see Homing.

Homing: The procedure by which a machine finds home. It moves the toolhead until it reaches a position the machine can sense, so that afterward it knows where the toolhead is.

Image Processor: A window in Studio that converts a photograph or other raster image into an SVG file of brush strokes in a chosen set of paint colors.

Job: The set of things open at a given time, which Studio turns into one or more output files. A job may hold one document or many.

Jog: Moving a machine's axes by hand, one step at a time. To jog your machine from its own controls, see its user guide.

JSON: A plain-text file format. Tools, toolsets, and palettes are exported and imported as JSON files, so you can back them up, move them to another computer, or share them; see §14.3 Importing and exporting toolsets.

Kerning: The spacing between neighboring letters. As a Handwriting Defect, the Kerning control varies that spacing rather than setting it.

Letter size: A Handwriting Defect that varies the size of individual written characters, making each one a little larger or smaller than its neighbors. The size of the type itself is set by Font size.

Media: Whatever the machine draws on. On the EggBot™ the PAPER SETTINGS section is titled MEDIA SETTINGS, and media size is measured in degrees rather than millimeters or inches.

Merge field: A field name in double curly braces, such as {{first_name}}, that Data Merge replaces with a value from the CSV file.

On-Machine Files: Files stored on the machine's microSD card, listed in Studio's Files section while the machine is connected.

Outline font: A regular computer font, such as a TrueType (.ttf) or OpenType (.otf) font. Each letter is stored as closed outlines that are filled in on screen, so a pen can trace only its edges; compare Single-stroke font.

Page: One sheet of a document. A document runs to more than one page only when text flow is set to use multiple pages.

Palette: In painting contexts, the tray of paint and water a brush visits between strokes, together with the layout Studio uses to find each location on it. In the Image Processor, a palette is instead the set of colors an image is reduced to.

Pan: One well of a palette, holding a single color.

Path: A shape in an SVG file, described as a line or curve rather than as pixels. Paths are what Studio turns into machine motion.

Plob: Short for "Plot Object": a highly specialized kind of SVG file, already processed for one machine model, that the machine draws without reprocessing it. Save as Plob appears only after Enable Plob output is turned on in Settings.

Plot: To draw with a machine, and the run that does so. A plotted page is drawn with a pen rather than printed.

Precision: A setting controlling how closely generated paths follow the source geometry. It is a tolerance, so a smaller value preserves more detail and a larger one simplifies.

Preset: A tool or toolset supplied with Studio and marked read-only. Duplicate a preset to get a version you can edit.

Pressure Depth: On the HandWriter, the spring pressure that holds the pen on the paper, set through the height at which the pen is installed.

Rapids: Fast positioning moves that run at the machine's own rate rather than at a set feedrate. Disable Rapids replaces them with controlled feedrate moves.

Raster image: An image stored as a grid of colored pixels, such as a PNG or JPEG photograph. A machine cannot follow pixels, so Studio converts a raster image to strokes in the Image Processor.

Render mode: The method the Image Processor uses to build a picture out of strokes: Paint Stripes, Paint Shapes, or Paint Shades.

Render New Preview (Text Add-On): A button in the Preview's header that rerolls the random seed for a fresh preview of the writing, Handwriting Defects included. It rerolls the page or merged document on screen and leaves the rest of a batch alone; Re-render all pages, in the Preview menu, rerolls the rest. A single document flowed across several pages is the exception, and rerolls as a whole.

Scrunch: A Handwriting Defect that compresses letters for a quicker, more casual feel, which also changes how much text fits on a page.

Section: A titled, collapsible group of controls in the Studio window, such as the FONT section or the PAPER SETTINGS section. Click its header, or the chevron in it, to expand or collapse it.

Setup Sheet: An on-screen summary of a processed job, which can be saved as a PDF. When a job produced more than one output file, the summary is titled Batch Setup Sheet.

Signature (Text Add-On): A feature that signs documents by placing a loaded signature file into the text workflow through the signature command {{sig}}.

Signature command: {{sig}}, {{sigalt}}, or {{siginit}}, written in a document where Studio draws a signature, an alternate signature, or initials. A signature command is not a merge field, and a CSV file is never required for it.

Single-stroke font: A font whose letters are drawn as single paths along the centerline of each stroke, rather than as outlines to be filled in. Letters come out as drawn lines, at pen width.

Soft Lift: A slower lift as the pen leaves the paper and at the top of its travel, set in the tool editor's Pen Landing & Lift section.

Soft Touchdown: A gentler final approach before the tool contacts the surface. The pen drops quickly to the Approach Above Paper height, then passes through contact at the slower Touchdown Speed.

Split button: A button whose face performs its usual action and whose chevron opens the other choices.

Stroke: The SVG property that draws a shape's outline, and the mark the pen makes. Studio plots the paths that have a stroke.

SVG: Scalable Vector Graphics, a vector image format based on XML.

Toast: A brief on-screen notification that clears on its own.

Tool: A single physical pen, marker, or brush. Each tool has a name and attributes such as its color, its speed settings, and any refill behavior defined for it.

Tool Macro Setup: The section of a brush tool's settings that sets what the brush does at the palette: Prime/Wash after a tool change, and Pre-Refill, Refill, and Post-Refill at each refill, with the palette locations each one visits.

Toolset: A saved, named collection of tools and their settings. A setting such as feedrate can be edited across every tool in the set at once.

Tooltip: A short description of a control that appears when you hover over it.

Transport: The connection method used to send a job to the machine, either USB or WiFi. The Preferred connection for uploads setting chooses which one Studio uses for an upload.

Travel move: A move made with the pen up, repositioning between drawn strokes rather than drawing.

US Letter: The 8.5" × 11" paper size.

WaterColorBot™: A Bantam Tools machine for brush-based painting workflows.

Z Offset: A per-tool adjustment to a tool's relative heights. It does not apply in absolute mode, where the field is hidden.