DEV Community: Matthew Armstrong

OvalFFR

Matthew Armstrong — Sun, 01 Nov 2026 21:36:16 +0000

Oval/slot fixed foveated rendering for OpenXR VR games, with a control panel. Built to cut GPU load for games streamed through ALVR.

Work in progress (v0.5.0). The control panel, the OpenXR layer plumbing and the Direct3D 12 code are in place, but the Direct3D 12 part (the foveation itself, Smooth low-res edge, and the new in-headset fps box, zone highlight and VRS check) has not yet been run in a real game or on a GPU, and the dual-GPU fix has never touched a real Windows registry. Direct3D 11 and Vulkan are not implemented. Read What works and what is untested before relying on it.

The screenshot uses simulated test data (a fake game report saying SteamVR is on the integrated card, Auto shrinking and smoothing running). Auto foveation and Smooth low-res edge are ticked here to show their status rows; both are **off by default. No real game, headset or GPU was involved.

What it does

Variable Rate Shading lets the GPU shade a block of pixels once instead of once per pixel. OvalFFR keeps a sharp oval (or slot) in the middle of each eye's image and shades the rest more coarsely:

Zone	Shading	Where
Full detail	1x1	inside the oval/slot
Middle ring	2x2	a gentle step around it
Low-res edge	2x2 or 4x4	everything else, including the corners, which the lens barely shows

The oval is centred on each lens from the headset's field of view. The panel's Horizontal and Vertical sliders set the sharp area's width and height, and the picture shows exactly which part of the view is low-res. The default setting is estimated to cut pixel-shading work by about 49 % (a unit test keeps it at 10 % or more); real fps gain is smaller, because geometry and memory work are not reduced.

Why not just use ALVR's foveated encoding? That compresses the frame after the game has rendered it, to save Wi-Fi bandwidth. It does not reduce the game's GPU work. OvalFFR reduces the rendering itself.

Quick start (click and launch)

Double-click the launcher for your system:
- Windows: OvalFFR-Windows.bat
- Linux: OvalFFR-Linux.sh (choose "Run")
- Mac: OvalFFR-Mac.command (first time: right-click, Open)
Press Install. The panel installs the layer and reads it back to confirm.
Start your game through ALVR as usual.
Press Check. It should say the layer was loaded by your game and that foveation is active. If it says pass-through, the reason is shown (for example "app does not use D3D12").
Move the sliders while playing. Changes apply within about a second. Uninstall removes everything.

Needs Python 3.8+ with tkinter (included with the python.org installers; Linux: sudo apt install python3-tk). Without tkinter the launchers fall back to text mode.

Is it doing anything? (fps box, zones, A/B test)

New in 0.5.0, because "is it actually working?" is the first thing to find out.

In the headset (also visible in the SteamVR mirror window on the PC). Keys work from any window, as long as the VR game has focus in the headset:

Keys	What it does
Ctrl+Alt+O	small fps box under the lens centre: `72 FPS / 90 HZ FFR ON`, and below it the estimated saving and the VRS check
Ctrl+Alt+Z	show the zones: yellow = 2x2, red = 4x4, purple = OvalFFR asked for low-res but the image the headset gets is full detail there (VRS did not reach it)
Ctrl+Alt+F	foveated rendering on/off (quick before/after)
Ctrl+Alt+[ / ]	sharp area 5% smaller / bigger
Ctrl+Alt+E	low-res edge 2x2 / 4x4
Ctrl+Alt+S / A	Smooth low-res edge / Auto foveation on/off
Ctrl+Alt+T	A/B test: FFR off, on, off, on, 10 s each (first 3 s of each ignored), then shows e.g. `A/B: OFF 64 ON 72 FPS +12%`. Press again to stop

Every key press shows what changed for 3 seconds. Setting changes are saved, so the panel follows them. Ctrl+Alt is AltGr on UK/European keyboards, so avoid typing AltGr+letter in other programs while a VR game runs.

The C++ copy of the shader on a made-up scene. Not a game or a headset.

The VRS check answers "is it doing anything?" directly. While the zones or Smooth low-res edge are on, the layer looks at one low-res block in every 16x16 pixels of the image the headset gets and counts how many are exact copies (what VRS produces).

About 90 % or more means VRS really reaches the picture.
Near 0 % (lots of purple) means the game draws that image at full detail. Usually that's because it renders into its own buffer and post-processes before handing the image over. VRS may still save work in the game's own buffer in that case, but OvalFFR cannot see that, and the fps numbers are the judge.
Flat single-colour areas look the same either way, so the figure is never exactly 0 %.

On the desktop: the panel's Mini fps window button opens a small always-on-top box with the live fps. Click it for more: late frames, spare time, the VRS check, buttons for every setting, Show zones in headset, Run A/B test, and the table of fps per setting.

The fps log (fps_log.csv in the settings folder) gets one row per setting, averaged over 2 minutes, plus a row whenever you change the setting after at least 20 s. Loading screens are left out, and the A/B test writes its own two rows. Text mode: --cli fps prints the per-setting table, and --cli fps send zones sends a command.

If every setting gives the same fps and it equals the headset's refresh rate, the game already runs at full speed and fps cannot rise. FFR then only buys headroom (the "spare time" figure, a rough measure). To see a difference, raise the render resolution in ALVR or SteamVR until the fps drops, then compare.

What works and what is untested

Part	Status
Mask maths (oval/slot, 3 zones, savings estimate, lens centring)	Unit-tested on Linux
OpenXR layer: negotiation, hooks, config hot reload, status/log	Tested on Linux against a fake OpenXR runtime (mock backend)
Python preview equals the C++ mask	Tested (`tests/test_mask_parity.py`)
Control panel	Run on Linux under a virtual display; screenshot above
Installer (files, manifest, read-back, uninstall)	Tested on Linux in a throw-away home folder
Edge cases (odd configs, NaN, huge sizes, FOV jitter, quad views, overlay apps)	Tested on Linux, including fuzzing and AddressSanitizer/UBSan. See docs/EDGE_CASES.md
Auto foveation: decision logic (simulated games) and layer wiring (fake runtime, closed loop)	Tested on Linux. Not run in a real game; no fps measured
Smooth low-res edge: the maths (a line-by-line C++ copy of the shader) and the layer wiring (fake runtime)	Tested on Linux. The shader passes the Khronos HLSL front end (glslang), not Microsoft's compiler. Never run on a GPU; cost not measured
fps box, zone highlight, VRS check (C++ copy of the shader), live fps, fps log, commands, focus handling, A/B test (fake runtime)	Tested on Linux. The D3D12 drawing and the Ctrl+Alt keys (Windows only) have never run
Mini fps window, panel following outside changes	Run on Linux under a virtual display (self-test + screenshot)
Dual-GPU: verdict logic, registry logic with undo	Tested on Linux with an in-memory stand-in for the registry
Dual-GPU: the real Windows registry write and the real graphics-card enumeration	Not run (Windows-only code, never executed)
Linux wrapper script for laptops with two GPUs	Run with fake `lspci` output; never on a real hybrid laptop
Windows layer DLL	Cross-compiled with mingw-w64; exports checked; never loaded by a real OpenXR loader
Windows registry install	Not run (written from the OpenXR loader documentation)
Direct3D 12 VRS backend	Compile-checked only; vtable slots verified by static asserts; not run on a GPU
Direct3D 11, Vulkan	Not implemented (the layer reports pass-through). Effort estimate for Linux/Vulkan: docs/LINUX_VULKAN_PLAN.md
macOS, Windows launchers	Not run (Linux launcher was run for real)
Real games, real fps numbers, ALVR end to end	Not tested
Low-end check (7th gen Core i3)	Not run. The app has no GPU requirement; the layer is a pass-through without VRS tier 2

Known limits

GPU needs Variable Rate Shading tier 2 (NVIDIA GTX 16 / RTX 20 or newer, AMD RX 6000 or newer, Intel Arc/Xe). Without it nothing changes and nothing breaks.
Only games that use OpenXR with Direct3D 12. OpenVR-only games are not seen by an OpenXR layer.
Games that create their render targets before starting the OpenXR session, or move descriptors with CopyDescriptors, may show no effect.
A game with its own dynamic resolution may spend the saved time on a sharper picture instead of more fps. Pin its resolution when comparing.
Fixed foveation is easier to notice than eye-tracked foveation. If you see the edge, raise the sliders or the ring.

Details and sources: docs/RESEARCH_NOTES.md. How it is built: docs/ARCHITECTURE.md.

Auto foveation (experimental, off by default)

Tick Auto foveation (experimental). Your sliders then become the sharpest the oval will go. If the game keeps missing display refreshes, the layer shrinks the sharp area in small, slow steps down to the floor you set; when frames are fine again it grows back. If shrinking does not help (the game is limited by the CPU or the network, not the GPU) it gives the quality back and stops trying for a while. The panel shows the live percentage. Text mode: --cli set auto=1 auto_floor=50.

Honest limits: the decision logic and a closed-loop run against a fake runtime are tested; it has not been run in a real game and no fps gain has been measured. It judges by xrWaitFrame timing, and I do not know yet how SteamVR/ALVR pacing looks to it. Other speed-up ideas that were researched and not built (peripheral frame generation, ...) are explained in docs/PERF_IDEAS.md.

Smooth low-res edge (experimental, off by default)

The low-res edge looks blocky because Variable Rate Shading shades one colour per 2x2 or 4x4 block and copies it to every pixel of the block. Tick Smooth low-res edge (experimental) and, after the game has drawn each eye, a small extra GPU pass blends those blocks into a smooth picture, like stretching a small image with bilinear filtering instead of nearest-neighbour. The idea: if the edge no longer looks low-res, you can afford a smaller sharp area or the stronger 4x4 edge. That is where the extra fps comes from. The smoothing itself saves nothing and costs a little.

Made by the C++ copy of the shader on a synthetic scene, magnified 3x. Not a screenshot from a game or a GPU.

What it will and will not touch:

The sharp area is never written.
It only changes a block whose pixels are all identical copies. Blocks with an object's outline running through them, film grain or other real detail are left alone. If a game draws into its own buffer and post-processes before handing the image over, the blocks are no longer exact copies, so the pass changes nothing there (and still costs its time).
Neighbouring blocks with clearly different colour count as an edge and are not blended in.
Strength (0-100%) sets how far each pixel moves towards the smooth version.
Text mode: --cli set smooth=1 smooth_strength=60. The panel's status area shows Smooth low-res edge: running, or why it is unavailable (for example no d3dcompiler_47.dll). Any failure switches off only the smoothing, never the game.

Measured on synthetic images (not hardware): the difference to the full-detail picture in the low-res zones drops by 88 % on a soft wavy scene and a lit ball scene. Outlines move by at most 0.005 (on a 0-1 scale). A full-detail image is left 100% unchanged (noise) or 99.99% unchanged (smooth scene).

Cost: not measured. It copies each eye image once and runs one full-screen pass. My rough estimate is about 150 MB of memory traffic per frame for two 2000x2000 eyes, which I'd guess at roughly 0.3-0.5 ms on a mid-range card. Treat that as a guess until it is measured. The shader is compiled the first time it is needed, which may cause one short hitch.

Laptops with two graphics cards

On a laptop with an integrated and a gaming GPU, the VR runtime (SteamVR, which hosts ALVR) decides which card every OpenXR game must use. Forcing only the game does not help if SteamVR itself started on the integrated chip. So OvalFFR does two things:

Detects it. When a game starts, the layer compares the card the runtime picked with the fastest card Windows reports, and the panel shows a green or red line in the Laptop with two graphics cards box (also in status-<pid>.txt as gpu_verdict).
Fixes it (Windows). Use gaming GPU for SteamVR sets Windows' own per-program "High performance" preference (the same switch as Settings > System > Display > Graphics) for the SteamVR and ALVR programs it finds, after you confirm the list. It reads every change back, remembers what was there before, and Undo GPU changes puts it all back exactly. Add program... does the same for any .exe (for example the game). Restart SteamVR afterwards.

Text mode: python3 src/main.py --cli gpu status, gpu force, gpu add C:\path\game.exe, gpu undo.

Linux: nothing is written to your system. Start ALVR or SteamVR through tools/ovalffr-gpu-linux.sh, for example ./tools/ovalffr-gpu-linux.sh alvr_dashboard. It looks at your graphics cards and, for that one launch only, sets NVIDIA's PRIME offload variables (__NV_PRIME_RENDER_OFFLOAD=1, __VK_LAYER_NV_optimus=NVIDIA_only) or Mesa's DRI_PRIME=1. --list shows what it found, --dry-run shows the command. Flatpak programs need flatpak override instead (the script header has the command).

Honest limits: only vrserver.exe is backed by a user report that this fixed a wrong-card problem; the other SteamVR programs are the same family but not individually confirmed. NVIDIA's and AMD's own control panels also have per-program settings, and I did not find out which one wins. None of this has been run on a real laptop.

Settings

Control	Meaning
Foveated rendering on	Master switch. Off = the layer does nothing.
Horizontal / Vertical	Size of the full-detail area as a % of the view width / height (20-100). With Auto on, this is the largest it will be.
Shape	Oval (lowest cost) to slot (rounded rectangle, keeps more of the frame sharp).
Middle ring	Thickness of the 2x2 step around the sharp area.
Low-res edge strength	2x2 gentle, or 4x4 strong (needs a GPU that supports it; otherwise 2x2 is used).
Centre on each lens	Use the headset's field of view to find each lens axis.
Auto / Never below	Auto foveation on/off, and the smallest the sharp area may shrink to (40-100% of your sliders).
Smooth low-res edge / Strength	Blend the blocky low-res pixels after the game draws (off by default), and how strongly (0-100%).
Show fps in the headset	The small fps box (Ctrl+Alt+O). Off by default.

The settings live in config.ini (Windows %LOCALAPPDATA%\OvalFFR, Linux ~/.config/ovalffr, Mac ~/Library/Application Support/OvalFFR). The layer writes one status-<process id>.txt per VR program that loads it, and layer.log, there too.

Text mode: python3 src/main.py --cli show, --cli set h=60 v=45, --cli install, --cli status, --cli fps. The mini window on its own: python3 src/main.py --mini.

Build and test

cmake -S layer -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
./build/core_test
./build/fuzz_test
./build/smooth_test
./build/layer_test ./build/libXR_APILAYER_OVALFFR_oval_ffr.so "$(mktemp -d)"
OVALFFR_BUILD=$PWD/build python3 -m unittest discover -s tests -v

Windows DLL on Linux: configure with a mingw-w64 toolchain (the vendored Microsoft headers are used automatically). The prebuilt DLL and Linux layer in prebuilt/ were made this way. Check the vtable slots with tests/check_d3d12_vtable.c (command inside the file).

Source code: The-Dorkknight/2026-10-31_1545_alvr-oval-ffr on GitHub

angry-putty

Matthew Armstrong — Sun, 01 Nov 2026 21:32:54 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN

Angry Putty 0.1.6-wip · © Matthew Armstrong · source-available under the
PolyForm Noncommercial License 1.0.0: free for personal, non-commercial use;
no commercial use without permission. Provided as is, with no warranty and no liability.
Only scan networks and log in to computers you own or have permission to use.
Read DISCLAIMER.md before use.

Angry Putty is an Angry IP Scanner-style network scanner and a
PuTTY-style terminal in one small window,
plus firmware that turns a cheap ESP32-S3 board into a USB dongle: plug it into a PC or
Raspberry Pi and it tells you that computer's address and lets you SSH into it from your phone.

Credit where it's due

The clever part of Angry Putty was done by other people. I have taken their ideas and tried to
make them quicker to use and plug and play.

Angry IP Scanner by Anton Keks and its contributors (free, GPL-2.0): the fast, friendly scanner that fills a table with every live device, its name and open ports. Angry Putty's Scan tab is built on that idea.
PuTTY by Simon Tatham and the PuTTY team (free, MIT licence): one small window that remembers your sessions and gets you into SSH, telnet or a serial port. Angry Putty's address bar and konsole follow that idea.

Angry Putty is a new program written from scratch: it contains none of their code, and it is not
affiliated with or endorsed by either project. If you want the full-featured originals, use them.
The heavy lifting inside Angry Putty is also done by other people's libraries (paramiko, pyte,
esptool, ESP-IDF, TinyUSB, lwIP, libssh2, xterm.js); see THIRD_PARTY.md.

	Status in 0.1.6-wip
Scanner: your own networks as the default range, ping, open ports, names, MAC	Works (tested on Linux)
`name.local` and "find every `.local` device" (mDNS), also on Windows without Bonjour	Works against a test responder; not yet tried on a real LAN
Address bar that remembers the last address and a history; `http://ip` opens the browser	Works
Konsole tabs: SSH (host-key checking), telnet, raw TCP, serial	SSH tested against OpenSSH 9.6; telnet/serial unit-tested only
Saved sessions, "open in system terminal"	Works on Linux; Windows/Mac terminals not tried
Flash the dongle from the app	Works: used on an ESP32-S3-Zero from Linux Mint (13-15 Oct 2026); 0.1.5 keeps the dongle's settings when re-flashing
Dongle firmware: USB network adapter + hotspot + web page + browser konsole (SSH, telnet, serial)	Works on an ESP32-S3-Zero (0.1.2): hotspot, phone page, and the plugged-in computer's address on Linux Mint and Windows 11 with no driver install. SSH through the dongle not yet tried
0.1.1: status LED, USB log, restart reasons and crash records, captive portal, capped WiFi power	LED, USB log and hotspot seen working on the board (0.1.1); crash records tested in Espressif's ESP32-S3 emulator
Phone/laptop SSH apps through the dongle (port 2222)	Written, not yet run on hardware
0.1.4: GadgetDesk option (off by default): cast the Pi's desktop to a phone on 8088, touch pad (double tap = HDMI desktop on/off), on/off from GadgetDesk	Builds; gesture logic tested on a PC; works end to end against GadgetDesk with the mock dongle. Not flashed or touched yet

Using it

Scan

The Range box fills in with your own networks (a big office network is trimmed to the /24 around you). Defaults lists every network card, the dongle hotspot and common home ranges.
You can type: 192.168.1.0/24, 192.168.1.10-50, 10.0.0.1-10.0.1.20, single addresses, host names, printer.local, or *.local to find every device that announces itself (Pis, printers, Klipper/Moonraker, ESPHome, Macs...). Mix them with commas.
Start scan. A host counts as alive if it answers ping or any probed port answers (even a refusal proves something is there). Untick Ping on networks that block it.
Double-click a row: SSH if port 22 is open, otherwise its web page. Right-click for SSH, telnet, http://, https://, copy IP/name, or save it as a session. Export CSV saves the table.

(The screenshot uses the built-in --demo data, so the addresses are simulated.)

Connect: the address bar and konsole

Type in Connect to and press Enter. It remembers the last address and keeps a history.

You type	It does
`192.168.1.20`	SSH (or the protocol picked on the left)
`pi@raspberrypi.local`	SSH as `pi`; `.local` names are looked up with Angry Putty's own mDNS if the system cannot
`ssh://pi@192.168.4.1:2222`	SSH on another port (this one goes through the dongle)
`telnet://192.168.1.9`	telnet
`http://192.168.1.50`	opens it in your web browser
`COM3`, `/dev/ttyUSB0`, `serial:///dev/ttyACM0?baud=9600`	serial konsole

The konsole is a real terminal (colours, htop, nano, vim):

PuTTY habits: selecting text copies it, right-click pastes; Ctrl+Shift+C / Ctrl+Shift+V also work.
The mouse wheel scrolls back. A+ / A- change the font size.
System terminal opens the same connection in your own terminal with the system ssh.
SSH logs in with your SSH agent, your keys in ~/.ssh (id_ed25519, id_ecdsa, id_rsa), then asks for a password. Passwords are never stored.
Host keys: the first time you are shown the SHA256 fingerprint (the same one ssh-keygen -lf prints). A changed key gets a loud warning and is never stored over the old one. Trusted keys go into Angry Putty's own known_hosts; your ~/.ssh/known_hosts is read, never written.

(Screenshots: a local OpenSSH test server, 127.0.0.1:2222.)

Sessions

Save a host as a named session (SSH, telnet, raw, serial, http, https) with port, user,
baud rate and an optional key file. Double-click to open; Open in system terminal uses your own terminal.

Settings live in ~/.config/angry-putty/ (Linux), ~/Library/Application Support/angry-putty/ (macOS)
or %APPDATA%\angry-putty\ (Windows).

The dongle

The dongle is an ESP32-S3 board running Angry Putty's firmware. Plug it into the computer you
want to reach:

 [ PC or Raspberry Pi ] ==USB== [ ESP32-S3 dongle ] ~~~ WiFi hotspot "AngryPutty-XXXX" ~~~ [ phone / laptop ]
   gets 10.66.0.2                10.66.0.1 | 192.168.4.1                                   browser: http://192.168.4.1

It appears to that computer as a USB network adapter and gives it the address 10.66.0.2. It offers no gateway and no DNS, so the computer's normal internet is not touched.
It reads the computer's DHCP request, so the page can also show its host name (e.g. raspberrypi).
It runs its own WiFi hotspot AngryPutty-XXXX (default password angryputty; change it in Settings).
http://192.168.4.1 shows the computer's address and a browser konsole: SSH (the dongle itself is the SSH client), telnet, raw TCP, or the serial console wired to the Pi's GPIO pins. Extra keys (Esc, Tab, Ctrl, arrows) are there for phones.
Any SSH app can log in through 192.168.4.1 port 2222; the computer's web page (port 80, e.g. Mainsail or OctoPrint) is at 192.168.4.1:8080.
GadgetDesk option (plug-in, 0.1.4, off by default). Turn it on with the desktop app's Turn GadgetDesk on button (Dongle tab, 0.1.5) or GadgetDesk desktop in the dongle's Settings to cast a Pi's GadgetDesk web desktop to your phone at 192.168.4.1:8088 (an Open :8088 button appears) and to use the touch pad below. With it off, the dongle has no 8088 forward and no touch pad, as in 0.1.3.
Touch pad (part of the GadgetDesk option): a short wire or a piece of foil tape on GPIO4 (any of GPIO1-14 except 3,
set on the page). With GadgetDesk on the Pi: double tap = HDMI desktop on/off, hold = off.
Switch the pad off and on from the page's Touch pad card or from GadgetDesk (its Touch button);
the card also shows the live reading so you can set the sensitivity. It only touches the pin: no
extra parts, and nothing else happens when GadgetDesk isn't there (3 red LED flashes).
Little OLED screen (0.1.6, optional). Wire a 4-pin I2C OLED (SSD1306 / SSD1315 / SH1106,
128x64 or 128x32) to 3V3, GND, SDA = GPIO8, SCL = GPIO9 and the dongle shows the computer's
address in big, full-brightness digits, then the hotspot, the ways in from a phone and its own
details, a few seconds each. Nothing happens if no screen is wired. Wiring, pages, settings and
troubleshooting: docs/OLED.md. Not run on a real screen yet.

(Taken with tools/mock_dongle.py, a pretend dongle on a PC, which shows a purple MOCK banner;
the computer shown is simulated, the SSH session behind it is real.)

The status LED

On the ESP32-S3-Zero the colour LED (GPIO21) shows what the dongle is doing. The same table is on
the dongle's page under What the LED means.

LED	Meaning
Red, green, blue once at power-on	Colour test. If you see green first, set LED colour order in the page's Settings.
Blue, 1 blink every 2 s	Hotspot on, nothing on the USB port
Blue, 2 blinks every 2 s	Computer connected by USB, waiting for it to ask for an address
Steady green	The computer has its address: ready
White flicker	Konsole traffic, or someone joined the WiFi
3 purple flashes after the colour test	The last restart was a crash
3 orange flashes after the colour test	The last restart was a power dip (brownout)
Fast red blinking	The WiFi hotspot failed to start

Other boards: choose a plain LED, another pin, or no LED in Settings.

When something goes wrong: health, log and USB log

The page's Dongle health card shows the last restart reason (power on, CRASH, brownout...), how many crashes and power dips there have been, the last crash recorded (task and code address), WiFi channel and power, and free memory.
The Log section shows the firmware's log live, and Before the last restart shows the last few KB written before a crash or restart.
Plugged into a computer, the dongle's USB port is also a serial port called Angry Putty log carrying the same log (the ESP32-S3-Zero has no USB-serial chip, so this is the only way to read it over a cable). In the app: Dongle tab > USB log. Any serial terminal works too (type help, status, prev or reboot).

If the dongle misbehaves, send the log (the window's Save... button) and the health card:
crash addresses can be decoded to the exact line with firmware/debug/angry-putty-<version>.elf.gz.

Flash the dongle

You need an ESP32-S3 board with a USB port wired to the chip's own USB (most S3 boards;
4 MB flash or more). ESP8266, the original ESP32, ESP32-C3 and C6 cannot do this: they have
no native USB that can act as a network adapter. The app checks the chip and says so.

Hold BOOT, plug the board into the computer running Angry Putty (or tap RESET while holding BOOT), let go.
Dongle tab > Detect chip (it picks the ESP32-S3's port itself and checks the chip and its flash size) > Flash firmware.
Unplug it and plug it in again without BOOT (remove any BOOT jumper or wire on GPIO0). The LED should show red, green, blue. From now on its USB port is a network adapter plus the log port, so to flash it again you always hold BOOT while plugging it in.

Re-flashing keeps the dongle's settings (WiFi name and password, LED, GadgetDesk option). Tick
Erase everything first to go back to the defaults.

Use it

Plug the dongle into the PC or Pi. On a Pi, use a normal USB-A port (or the Zero's USB OTG port with an adapter).
Join the AngryPutty-XXXX WiFi from your phone or laptop (password angryputty). A phone will say Sign in to network (like hotel WiFi): tap it, or open http://192.168.4.1 in your browser. The phone stays connected and keeps using mobile data for the internet.
Open http://192.168.4.1 (or press Refresh in the app's Dongle tab).
Press SSH, type the user name and password. Or connect any SSH app to 192.168.4.1 port 2222.

SSH must be switched on in the computer. On Raspberry Pi OS: Raspberry Pi Imager's settings,
or sudo raspi-config > Interface Options > SSH. On Windows: Settings > Optional features >
OpenSSH Server. No SSH? Use the serial console:

Dongle (ESP32-S3)	Raspberry Pi header
TX (GPIO17 by default)	pin 10, GPIO15 (RXD)
RX (GPIO18 by default)	pin 8, GPIO14 (TXD)
GND	pin 6 (GND)

3.3 V logic on both sides; never connect the Pi's 5 V pins. Enable the console with
sudo raspi-config > Interface Options > Serial Port (login shell: yes). The default pins are
arbitrary: set the ones your board has free in the page's Settings.

Build the firmware yourself

See firmware/README.md. In short, with ESP-IDF 5.4:
cd firmware && idf.py set-target esp32s3 build. GitHub Actions also builds it on every push.

HOW_IT_WORKS.md: what each part reads, changes and never does.
RESEARCH_NOTES.md: the research, decisions, what was tested and how, ideas, and the lessons carried over from Skipper Flipper.
docs/HARDWARE_LOG.md: every test on real hardware, with results.
firmware/README.md: building and flashing the dongle firmware by hand.
THIRD_PARTY.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md.

Tests: python -m pytest (add xvfb-run on Linux for the GUI test; set
ANGRY_PUTTY_TEST_SSH=user:password@host:port to include a live SSH login).

Source code: The-Dorkknight/angry-putty on GitHub

Pasta Inspector

Matthew Armstrong — Sun, 01 Nov 2026 20:48:24 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN. Version 0.6.0-wip. Proof of concept: the detector has only been tested on simulated prints, and the firmware has not yet been run on a real ESP32 board.

Licence: PolyForm Noncommercial 1.0.0. Source-available, non-commercial use only. Provided as-is, with no warranty and no liability. Pasta Inspector is not a safety device: it can miss a failed print, and it can stop a good one.

A standalone, offline "spaghetti detector" for Klipper printers that runs entirely on a ~£15 ESP32-S3 camera board, or on the Klipper host itself with any USB webcam. There is no Docker, no cloud and no account. The camera talks to Moonraker over your own WiFi, or over a USB cable plugged into the printer (for example an Elegoo Neptune 4 running OpenNept4une). When it sees filament where the G-code says there shouldn't be any, it works out which part failed. If it is sure, it excludes just that part and the rest of the plate carries on. If not, it pauses the print.

Two versions, one program

	ESP32 camera	Klipper host + any USB webcam
What you need	A ~£15 ESP32-S3 camera board	The computer that already runs Klipper (a Pi, thin client, mini PC) and any USB webcam, for example a 3–5 megapixel one or the one crowsnest already uses
Folder	`esp32/`	`klipper-host/`
Set up	Flash it with the Flasher, then the steps below	`bash pasta-inspector/klipper-host/install.sh` (docs/KLIPPER_HOST.md)
Needs the other one?	No	No. No ESP32 is involved
Extra	Can talk to the printer over a USB cable instead of WiFi	Can ask a pre-trained neural network for a second opinion (optional, `install.sh --ai`)

Both run the same program from shared/: the detector, the printer-sensor watch, the web page, every setting and the Moonraker link. A fix there reaches both. The Klipper-host version is new in 0.6 and has not yet been run on a real printer.

Screenshots are of the included simulator (pretend printer + camera), not of real hardware.

What it does

Reads the G-code's own idea of where plastic belongs. Klipper's [exclude_object] gives every object's outline. Moonraker also reports where the toolhead is, how much filament has been used and the print state.
Projects those outlines into the camera image. This uses a one-off calibration where you click 4 bed points. Each outline is swept upwards to the current print height.
Compares every frame with a reference image. It masks out the toolhead along the path it has just travelled and treats its shadow specially. The threshold adapts to the camera's noise, and lighting changes and small camera shakes are allowed for.
Flags new material outside every outline, and changes to the finished lower part of each object. Spaghetti, a blob dragged across the bed, or a part knocked loose all count.
Waits until it's sure. A change has to stay in the same place for 3 frames (by default) before it counts. Shadows, reflections and noise move around, so they never do.
Works out which part failed, from two clues:
- where the mess is: next to one part and near no other
- when it grew: only while one part was being printed. Klipper says which part that is. This is the clue that still works when parts stand close together.
Acts:
- If it is sure which part failed and other parts remain, it sends EXCLUDE_OBJECT NAME=... and the rest prints on.
- Otherwise it sends PAUSE, or EMERGENCY STOP / a console warning, whichever you choose. It also does that after 3 excluded parts in one print, when trouble comes back within a minute of an exclusion, and when the failed part is the only one still being printed.
- It only acts on fresh information: if the link to the printer is down, or the printer's status is more than a few seconds old, it does not judge the print at all, and an action that could not be sent is tried again when the link is back.

You can switch excluding off, or change the limit, under Detector (If one part fails and the others are fine).

At the start of every print it checks its own calibration, so a camera that got nudged still lines up. It does this once the first layers are down (not while the printer is still heating and probing):

If the slicer script is installed, each print carries 4 small reference marks on its first layer. The camera finds them and corrects its calibration.
If there are no marks (no slicer script, a print too big to leave room, or marks it can't see), it uses the print itself: the edges of the parts' first layers, which Klipper's outlines say where to expect.
If neither can be trusted, it changes nothing. The same goes when watching only starts well into a print (the camera was switched on late): the status then says the check was skipped.

Dry run is on by default. The camera only logs what it would have done until you switch dry run off.

It runs at the 1–5 fps you'd expect from an ESP32-S3. The detector itself takes about 1 ms per frame on a PC. On the ESP32 it hasn't been measured yet, but we expect a few tens of milliseconds.

How well does it work? On 8,640 randomised simulated prints:

4 false alarms on 2,760 clean prints with shadows, lighting jumps, camera shake, slightly-off calibration and a position report that runs ahead of the toolhead. All four were pauses, on tightly packed plates in the hardest conditions.
With parts spread over the bed:
- Spaghetti found 98–100% of the time, typically within 2.5–8.5 s.
- Knocked-off parts found 71–85% of the time.
- Small blobs found 45–91% of the time.
Excluding just the failed part (spaghetti, several parts on the bed):
- Parts spread out: the rest of the plate was saved in 39–59% of prints. Nearly all the others were paused.
- Parts packed 8 mm apart: saved in 36–48%, and in 24–27% in hard conditions. Without the timing clue it was 1%.
- A good part was excluded in 0–2% of prints (4% on a bed-slinger in hard conditions).
Tightly packed plates hide failures. With 9 parts 8 mm apart, spaghetti was found 82–87% of the time and took about a minute. Knocked-off parts and small blobs were mostly missed.
Blind to mess on top of a part's own outline.
A camera knocked 6 px after calibration caused false alarms on 41% of clean prints. Using the print's own outline to re-align: 2.5%. With reference marks from the slicer script: 0%.

These are simulated, not real-world, numbers. Details are in docs/ENGINE_TESTS.md.

What exists and what doesn't

Part	State
G-code-aware detector (C++, shared by firmware and PC tools)	Written. Unit tests, a randomised simulated-print benchmark, sanitiser and fuzz runs: see ENGINE_TESTS.md
ESP32-S3 firmware (camera, Moonraker link, web UI, settings)	Written. Built and linked for both boards with the real ESP32 compiler and the official Arduino core; the images ship with the Flasher (`esp32/firmware/prebuilt/`). Not yet flashed or run on a real board; the PlatformIO build first runs on GitHub when you publish
On-device web UI (calibrate, status, settings, dry run)	Written, tested against the simulator
USB link (camera's native USB port ↔ a small bridge service on the printer's computer)	Written. The bridge and the protocol are tested end to end on a PC with a pretend camera and a fake Moonraker. Not run on a real camera or printer
Slicer script (PrusaSlicer, OrcaSlicer, SuperSlicer, Cura): object outlines + reference marks	Written. Tested on G-code from PrusaSlicer 2.7.2 and on hand-made Cura-style and Orca-style files. Not tested on real OrcaSlicer or Cura output, and no processed file has been printed
Calibration check at the start of each print, from printed reference marks or from the print's own outline	Written, tested on simulated prints only
Camera setup tab in the desktop tool: guided calibration on the live picture for any camera position, and a slicer script written for that camera's view	Written. Its logic is tested with a stand-in camera. Not used with a real camera yet
Calibration print (bed-sized STL, click its squares to calibrate, tower for the camera angle, skew check for Klipper)	Written. The STL is checked to be closed and the skew numbers against Klipper's formula. Not printed yet
Klipper-host version (`klipper-host`): the firmware built for Linux, with a USB webcam via crowsnest or `/dev/video*`, installer with a systemd service and Moonraker's update manager	Written. Runs end to end against a pretend printer and webcam on a PC, also under ThreadSanitizer and AddressSanitizer, and was reviewed independently. CI is set up to build and test it on x86 and ARM (it first runs when the repository is published). Not yet run on a Raspberry Pi, with a real webcam or with a real printer
Klipper macros (`PASTA_INSPECTOR_SNAP`, `PASTA_INSPECTOR_REFS`)	Written. Templates checked with Jinja2, not run in Klipper
Elegoo Neptune 4 / 4 Pro guide (OpenNept4une, USB)	Written from documentation, not tried on a printer: docs/NEPTUNE4.md
Desktop tool (live view, calibration, record, replay, tuning)	Written, tested against the simulator
PC simulator and fake Moonraker for bench testing	Written, tested
The printer's own sensors (filament sensors, hotend and part fan tachometers, hotend heater power), both versions	Written. Found by name and watched while printing; tested against Klipper-shaped messages and a pretend printer. Not run against a real Klipper or sensor
Neural network second opinion (Klipper host only, optional): PrintGuard's pre-trained network, downloaded on request, run by Pasta Inspector itself	Written. Gives the same numbers as ONNX Runtime on the same file. Its accuracy on real prints is untested here; by default it only advises. On the ESP32: no network fits, see RESEARCH_NOTES section 14
Telegram/Discord/phone notifications	Not started. Actions appear in the Klipper console and the camera's event log
Saving snapshots of detections	Not started

Hardware

Either a USB webcam on the Klipper host (see docs/KLIPPER_HOST.md; then skip to step 3 below), or:
An ESP32-S3 camera board with PSRAM. Pin maps are included for:
- Seeed XIAO ESP32S3 Sense (default)
- Espressif ESP32-S3-EYE, and boards that copy its pinout, such as the common "Freenove ESP32-S3-WROOM CAM"

The old ESP32-CAM (non-S3) is not supported.

A USB data cable, if you want to use USB instead of WiFi. On boards with two USB sockets, use the one marked USB or OTG (the ESP32-S3's own USB), not the UART one.
A rigid mount that sees the whole bed. A mount on the printer frame is best. On a bed-slinger (Ender-3 style), either mount the camera on the bed or tick the bed-slinger option (see Known limitations).
Steady lighting. An always-on LED strip helps a lot.
A Klipper printer with Moonraker (Mainsail/Fluidd setups, Forge-X/ZMOD on the Flashforge AD5M, etc.) and [exclude_object] enabled.

Set it up, step by step

Using a webcam on the Klipper host instead of a camera board? docs/KLIPPER_HOST.md replaces steps 1 and 2; then go on with step 3.

1. Flash the camera

Open the Flasher: in the esp32 folder, double-click Flasher.bat (Windows), Flasher.command (macOS) or Flasher.sh (Linux), or run

python3 esp32/flasher.py

Pick your board (XIAO ESP32S3 Sense, or ESP32-S3-EYE / Freenove ESP32-S3 CAM), plug the camera in by USB and press Flash. The firmware for both boards ships in esp32/firmware/prebuilt/, so nothing is built or downloaded, except Espressif's esptool, which the Flasher installs into a private folder (~/PastaInspector/esp-venv) when you press Install esptool the first time. It finds the camera's port by itself, checks the firmware file against its recorded SHA-256, and asks before it writes anything. Tick Erase everything first the first time.

The shipped firmware has been built and linked, but not yet run on a board. Its status is in esp32/firmware/prebuilt/<board>/build-info.json and on the Flasher's screen.

Linux: if the flash says permission denied, run sudo usermod -aG dialout $USER, then log out and back in. The window needs Tk: sudo apt install python3-tk.
Board not found: hold BOOT, tap RESET, release BOOT, and press Flash again.

Developers can still build and flash with PlatformIO: python3 pasta_inspector.py flash (or flash eye). It installs PlatformIO for your user the first time (a big download). esp32/tools/build_firmware.py builds the shipped images without PlatformIO, from the official arduino-esp32 2.0.17 package.

Over USB to the printer already? Stop the bridge first (sudo systemctl stop pasta-inspector-bridge on the printer's computer): while it runs it keeps the camera's port to itself.

You can also flash a firmware built on GitHub: each zip on the repository's Releases page comes with a FLASHING.txt that gives the addresses and the command.

2. Connect it to your WiFi and printer

On first boot the camera makes its own WiFi network called PastaInspector-XXXX-YY, with password spaghetti (the two letters at the end are chosen once at random, so cameras in one room are easy to tell apart).

Join that network and open http://192.168.4.1.
Fill in Device & printer:
- your WiFi name and password
- the printer's IP address (Moonraker, port 7125)
Press Save device settings, then Reboot.

After the reboot the camera is at http://pasta-inspector.local, or at its IP address, which your router can show you. Its own setup network switches off once it is on your WiFi. If it cannot get onto your WiFi when it starts (wrong password, router still booting), the setup network comes back after 20 seconds and the camera keeps trying your WiFi once a minute.

A first-start notice explains the risks. Tick I understand to continue.

3. Make Klipper report object outlines

Add this to printer.cfg and restart Klipper:

   [exclude_object]

PAUSE needs [pause_resume], which Mainsail and Fluidd setups already have. [respond] is optional: with it, the camera's reasons also show up in the Klipper console. Without it the camera still pauses and excludes.

Make your slicer label objects:
- PrusaSlicer 2.7+ and OrcaSlicer have a Label objects option.
- Cura needs Moonraker's G-code processing ([file_manager] enable_object_processing: True in moonraker.conf).

See Mainsail's exclude-objects guide.

Or install the slicer script, which adds the outlines itself for all of these slicers.

Without object outlines the camera has nothing to compare against. The status panel then says Objects: none. If even one part in a print has no outline, the camera does not judge that print at all and the status says why.

4. Calibrate (once, and again if the camera moves)

Every camera sits somewhere different: above, at the front, off to one side. Calibration tells it where the bed is in its picture. The easiest way is the desktop tool's Camera setup tab (python3 pasta_inspector.py, then Connect), which shows the live picture and walks you through it:

Your bed. Pick the size, or type it. Tick Bed-slinger if the bed moves and the camera is fixed to the frame.
Mark four spots. Any of the three ways works for any camera position:
- Bed corners: click the four corners in the picture, starting front-left.
- Nozzle: if the camera can't see all four corners, move the nozzle to four far-apart spots about 1 mm above the bed (with your printer's own controls) and click its tip each time. The tool reads X and Y from the printer.
- Calibration print: press Make print STL..., print it, leave it on the bed and click the centres of its four corner squares. Nothing needs to be moved by hand, and square centres are easier to hit than bed corners hidden under clips. See The calibration print.

On a bed-slinger, home the printer first, leave the bed where it stops, and use the corners; the tool remembers that bed position.

Camera angle. Raise the nozzle 30 mm or more, press Measure and click its tip. With the calibration print, press Use the tower and click the middle of the tower's top instead. This tells the camera how far parts lean in its picture as they get taller. A camera looking straight down gives about 0. You can skip this and tune Height shift X/Y later.
Check and save. The cyan outline should sit on the edge of the bed, and the pink + should follow the nozzle. With the calibration print, the orange outline should sit on the print, including the small tab and the tower's top. Then Save to the camera.
Slicer script (optional): see below.

You can also calibrate without the desktop tool: press Calibrate bed in the camera's web page and click the four bed corners (front-left, front-right, back-right, back-left), or type the coordinates of four other spots you know. Set the bed size under Detector → Advanced.

The calibration print

A bed-sized print that takes about 5 g of filament: a thin border 10 mm inside the bed edge, four 20 mm squares near the corners (numbered 1 front-left, 2 front-right, 3 back-right, 4 back-left), a small tab just right of square 1 so you can tell which corner is which, and a hollow 20 mm tower in the middle. Everything except the tower is 0.6 mm tall.

Make it in the Camera setup tab (Make print STL...: set the gap from the bed edge and the tower height), or from the command line: python3 pasta_inspector.py calprint stl --bed 220x220 (--margin 15 if clips or a wiper are in the way, --tower 0 for no tower).
Slice it with your usual settings. Leave it where the slicer puts it (centred) and do not rotate it: the camera setup assumes each square is where the file put it. Use PETG or ABS if the bed stays hot, since PLA softens.
Skew check (optional). With a steel rule, measure between the outer corners of the corner squares (the corner nearest each bed corner): AC is square 1 to square 3, BD is square 4 to square 2, AD is square 1 to square 2. These are Klipper's letters. Type them into Skew... or run python3 pasta_inspector.py calprint skew AC BD AD. You get the skew angle and the SET_SKEW XY=... line for Klipper's [skew_correction]. The camera cannot measure skew itself: perspective hides it.

How much it helps: in simulated prints, a perfect calibration found no more failures and gave no fewer false alarms than an ordinary hand-clicked one, because the camera re-aligns at the start of every print anyway (see RESEARCH_NOTES.md, section 11). The print makes setup easier and gives you a skew check. It does not make detection more accurate. It has not been printed yet.

Next, start a print and check that the green areas sit on the parts as they grow. If they lean the wrong way as the print gets taller, adjust Height shift X/Y.

5. Watch a few prints in dry run, then arm it

Leave Dry run ticked for a few prints. Any detections appear in the event log as DRY RUN would pause....
When you trust it, untick Dry run. The header chip turns ARMED.

USB instead of WiFi

The ESP32-S3 has its own USB port, so one cable to the printer can carry both power and data. A small service on the printer's computer (the bridge) passes messages between the camera and Moonraker, and puts the camera's web page on port 7130 of the printer.

camera ──USB──> printer's computer: pasta-inspector-bridge ──> Moonraker (127.0.0.1:7125)
                                     └─ web page at http://<printer-ip>:7130

On the printer's computer (over SSH), as the normal user:

git clone https://github.com/The-Dorkknight/pasta-inspector.git
bash pasta-inspector/esp32/bridge/install.sh

The installer sets up the service, adds you to the dialout group, copies the optional Klipper macros and adds [include pasta_inspector.cfg] to printer.cfg (a backup is kept). --uninstall undoes it.

The bridge only opens USB devices made by Espressif (the ESP32's maker), never Klipper's own boards, and sends nothing to a port until a Pasta Inspector has said hello on it. It passes on to Moonraker only the few requests the camera needs (see SECURITY.md).

Then plug the camera in and open http://<printer-ip>:7130. Link mode under Device & printer chooses between Auto (USB when the bridge answers, otherwise WiFi), WiFi only and USB only.

The full walk-through for the Elegoo Neptune 4 / 4 Pro with OpenNept4une is in docs/NEPTUNE4.md. The same steps should apply to any Klipper host with a free USB port (a Raspberry Pi, for example); none has been tried yet.

Slicer script: outlines and reference marks

slicer/pasta_inspector_post.py is a post-processing script for PrusaSlicer, OrcaSlicer, SuperSlicer and Cura.

The best way to set it up is step 5 of the desktop tool's Camera setup tab: Write the slicer script. It writes a copy of the script with your camera's view built in (to ~/PastaInspector/slicer/), installs it into Cura if Cura is on that computer, and gives you the line to paste into PrusaSlicer/OrcaSlicer (Output options → Post-processing scripts). The reference marks are then printed where your camera can see them, and made bigger (up to 20 mm) if they would be too small in its picture. Preview a G-code file shows on the live picture where a file's parts and marks will land. Do it again whenever you re-calibrate.

The same from a terminal:

python3 pasta_inspector.py slicer --camera http://pasta-inspector.local    # or http://<printer-ip>:7130 over USB
python3 pasta_inspector.py slicer                                        # without a camera view

In Cura (4.9 or newer): Extensions → Post Processing → Modify G-Code → Add a script → Pasta Inspector. If you copy the script into Cura's scripts folder by hand, name it PastaInspector.py.

Each sliced file then gets:

Object outlines for Klipper (EXCLUDE_OBJECT_DEFINE and start/end markers), worked out from each object's own moves, unless the slicer already wrote them.
4 reference marks: 10 mm squares, one layer thick, printed about 14 mm outside the corners of your parts, just before the first part starts. With your camera's view built in, corners the camera can't see are swapped for free spots it can. They are ordinary Klipper objects named PASTA_INSPECTOR_REF_1..4. The camera reads their positions from Klipper, looks for them in the image once the first layer is down, and corrects its calibration for that print: a shift, or with all 4 marks a shift plus a small turn. Corrections larger than 24 px are refused, and the status then tells you to recalibrate.
Optionally (--snap-every N), a call to the PASTA_INSPECTOR_SNAP macro every N layers, which parks the toolhead for a moment so the camera gets a clear view. This is mainly for bed-slingers. It is left out of files printed one object at a time ("complete objects") and of spiral-vase files, where parking would run into a finished part or leave a blob; the macro itself also refuses to move when the nozzle is lower than it was at an earlier call.

Options: --no-refs, --ref-size 8, --ref-margin 20, --bed 225x225 (for files that do not state their bed size; if the file states one too, marks are kept on the part of the bed both agree on), --no-outlines, --snap-every 5, --camera view.json, --no-camera, --strict. Running the script twice on one file does nothing the second time.

When the script has to skip something, it says why in ; Pasta Inspector note: lines at the top of the G-code file. Slicers only show a script's messages when it fails, so look there; or add --strict, which makes the export fail with the reason instead. If anything unexpected happens while it works, it leaves your file exactly as the slicer wrote it.

Files sliced with object labels for Marlin (M486) are understood too: the script turns them into Klipper's labels.

If the print leaves no room for marks, or none where the camera can see, the script says so in a note at the top of the file and prints none. The camera then lines itself up on the parts' own outlines instead. With a camera view the script also warns when a part is partly outside the camera's picture, where it can't be watched.

The script leaves the marks out, and writes the reason at the top of the file, whenever it can't be sure they are safe: with a raft, a round bed, an unknown bed size, or a file that never says where the nozzle is before the first part. It keeps them clear of skirts, brims, purge lines and wipe towers that are in the file.

Check the first layer of a processed file in your slicer's or Mainsail/Fluidd's G-code viewer before you print it. The marks are extra moves added to your file, and no processed file has been printed yet. In particular, a purge line drawn by a PRINT_START macro is not in the file, so the script cannot avoid it: if a mark lands on yours, move the marks with --ref-margin.

Reference marks can also be given by hand, without the slicer script: PASTA_INSPECTOR_REFS POINTS=[[20,20],[200,20],[200,200],[20,200]] SIZE=10 (from klipper/pasta_inspector.cfg).

The desktop tool, tab by tab

Start it with python3 pasta_inspector.py. Type the camera's address, or press Use simulator, then Connect. The version and build date are always shown in the title and status bar.

Camera setup: the guided calibration and slicer-script export described in step 4.

Live: the camera view with the overlay, status and event log, the Detection enabled and Dry run switches, and a quick four-corner calibration.

green: plastic allowed by the G-code
teal: finished part bodies (watched)
blue: ignored (toolhead / excluded parts)
orange: suspicious, not yet confirmed
red: anomaly
dark: off the bed

Detector: every detector setting, with load/send to the camera and open/save as JSON.

Record: saves frames, plus the printer state at that moment, into a session folder. Each frame is about 19 KB. Record good prints and failures.

Replay: runs the exact firmware detector (sc_replay) over a recorded session, either with the session's own settings or with the Detector tab's. It lists which frames would have triggered and lets you scrub through the overlay. This is the way to tune thresholds without printing anything.

Help: the setup steps in short form.

The camera's own web page works on a phone too:

Try it without hardware

python3 pasta_inspector.py sim            # pretend camera + printer at http://127.0.0.1:8080
python3 pasta_inspector.py sim --auto     # spaghetti appears by itself after ~20 s (dry run: only logged)
python3 pasta_inspector.py sim --auto --live   # ... and the pretend printer really gets the command
python3 pasta_inspector.py                # desktop tool -> "Use simulator"
python3 pasta_inspector.py host-demo      # Linux: the Klipper-host version against a pretend printer + webcam

The simulator serves the real web page and runs the real C++ detector. Like a new camera it starts in dry run. Its bar at the top can add spaghetti, flicker the lights or restart the print.

To bench-test a real camera without a real printer, run the fake Moonraker on your PC:

python3 pasta_inspector.py fake-printer   # listens on port 7125

Then:

Set the camera's printer host to your PC's IP.
Calibrate on a sheet of paper.
Drop some filament on it.

The EXCLUDE_OBJECT / PAUSE commands are printed in the terminal instead of reaching a printer.

More docs

HOW_IT_WORKS.md: the detector, what it reads, what it changes and what it never does
docs/KLIPPER_HOST.md: running it on the Klipper host with a USB webcam, instead of on a camera board
docs/DETECTION_METHODS.md: research into further ways to catch failures (printer signals, camera methods, machine learning, licences)
docs/NEPTUNE4.md: Elegoo Neptune 4 / 4 Pro with OpenNept4une, over USB
docs/ENGINE_TESTS.md: how the detector was tested, and the numbers
docs/API.md: the camera's HTTP API, and the USB link protocol
docs/RESEARCH_NOTES.md: what was looked up, tried and measured, how sure each point is, and what is still unknown. A copy is attached to every release
CHANGELOG.md · CONTRIBUTING.md · SECURITY.md · THIRD_PARTY.md

Copyright Matthew Armstrong (The-Dorkknight). Licensed under the PolyForm Noncommercial License 1.0.0. This is not legal advice.

Source code: The-Dorkknight/pasta-inspector on GitHub

Skipper Flipper

Matthew Armstrong — Sun, 01 Nov 2026 18:33:08 +0000

An experimental ESP32 pseudo Klipper port. (Repository and package name: esp-printhost.)

GPL-3.0 · Linux (Mint / Ubuntu) · C++17 core + Python tools · Project page

Licensed under the GNU General Public License v3.0, see LICENSE. No warranty and no liability: this is provided as is. You use it at your own risk, on your own hardware, and the author is not responsible for damage to boards, printers or anything else.

What this is

An idea for reviving old, donated 3D printers: a cheap ESP32-S3 becomes the "brain" (WiFi, web UI, text config, motion planning) and the printer's original board becomes a simple slave running a modified Klipper MCU firmware. The full plan is in docs/DESIGN.md.

Target hardware: ESP32-S3 only for the host ("master"). Status (29 October 2026): mostly working, needs tuning and proper testing. On real hardware (docs/HARDWARE_LOG.md), installed in a WEEDO Tina 2 with a BTT SKR Pico running plain Klipper v0.13.0:

the WiFi pages, console and printer.cfg editor; firmware updates over WiFi;
the Klipper link, clock sync, board configuration and recovery from board power cycles;
temperatures, heating, PID tuning and Klipper's heater safety checks;
the motor test, TMC2209 set-up, stallGuard and full homing of X, Y and Z (2026-10-27);
a whole print file, run end to end (2026-10-27): in mid-air, because the Tina 2's flexible Z gave no reliable stop to set a Z offset from;
the micro SD card, the little OLED, touch buttons through the case, the hotend fan;
the print benchmark (2026-10-29): 12 layers of a print path (9,617 lines, about a million steps) through the whole motion pipeline and the real board, drivers off, in 121.8 s, with the ESP32's printer task busy about 44 % of one core, of which about 14 % is real work and the rest mostly waiting for the board's acknowledgements (docs/BENCHMARK.md);
integer motion maths (INT32/64 test build, 2026-10-29): input shaping with pressure advance costs 10 % of one core at 100 mm/s instead of 19 %; the shaping work itself is about 3.7 times faster.

Not yet: a real printed part; input shaping, pressure advance, bed mesh and the other tuning features on a moving printer; the part-cooling fan and the third fan output (possibly a broken wire). Next test bench: a QIDI X-Smart 3 (CoreXY) with an SKR Pico; the Tina 2 is retired as the bench (no sharp Z stop, and its tiny Y motor overheats). The whole story, including every mistake: A Frankenstein Experience (PDF).

New features by date, and whether each has been on hardware, are in CHANGELOG.md.

Part	State
Klipper wire protocol (CRC16, VLQ ints, framing, resync, data dictionary)	Unit-tested; works on hardware (ESP32-S3 to SKR Pico)
ESP32-S3 firmware (`firmware/esp32s3`): WiFi access point, status page, console, `printer.cfg` editor, test bench, printer page, the Klipper host's jobs (heaters, TMC2209, moves, homing, printing from flash). Shipped ready to flash	On hardware: link, heating, PID, motor test, TMC2209, stallGuard, full homing (2026-10-27), a print file run in mid-air (2026-10-27), WiFi updates, the print and motion benchmarks (2026-10-29). Not yet: a real printed part
`skr-pico-uart` printer-board firmware (plain Klipper v0.13.0, serial on UART0; the ESP32-S3 firmware is the only bespoke part)	Works on hardware: link, heater, thermistor, steppers, TMC UART, DIAG pins (with the 2026-10-10 build, which also held the since-removed, never-used segment queue; why it went)
Motion planner + G-code engine (lookahead, junction deviation, trapezoids, pressure advance, G-code state)	On hardware for homing, a print file in mid-air and the benchmarks; checked in simulation for exact positions, speed and acceleration limits. Never yet used for a real part
Delta kinematics (`kinematics: delta`, docs/DELTA.md); DECKHAND needs its own delta build	PC-tested only (head path vs the arm geometry, three-endstop homing); never on a real delta; no delta calibration yet
Pasta Inspector dongle support (`/websocket`, Moonraker-style: exclude object, pause, M112)	Engine PC-tested; firmware written but not compiled or tried with a real dongle (docs/PASTA_DONGLE.md)
Other board presets (generic RP2040, Creality 4.2.x, RAMPS mega2560, Ender-3 1.1.x, USB SKR Pico)	Compile only; never run on hardware
Flasher app (`flasher.py`): Slave tab (printer board) and Master tab (ESP32-S3)	ESP32-S3 flashing used on hardware on Linux Mint. Other paths (SD card, avrdude, Windows/macOS) tested with mocks only
Firmware build tool (CLI + Slave tab "My own build")	Works on Linux (sandbox and the author's Linux Mint laptop); Windows needs WSL
`mcu_probe`, `fake_mcu.py`, one-command setup, Tools window	Working on Linux Mint. Probe tried on an SKR Pico over USB
Real printing	A print file ran end to end on the Tina 2 (2026-10-27) but in mid-air (Z offset not found); upload, print from flash or SD card, pause / resume / cancel are simulated. No real part printed yet
Micro SD card (`firmware/esp32s3/main/sdcard.c`)	Works on hardware (2026-10-19: mount, file list, upload; printing from it not yet tried): SPI card for big G-code files, file list / print / delete on the Printer page, `SDCARD_PRINT_FILE FILENAME=`, M20/M23/M24 (the command side is unit-tested). See docs/SD_CARD.md
Buttons on the case (`firmware/esp32s3/main/panel.cpp`, `host/src/panel.cpp`)	Touch works on hardware (2026-10-26: Preheat and Home from staple pads melted into the Tina 2's case); up to four touch pads (bolts on wires) or switches: Preheat, Home and E-stop (both on a 1 s hold), Unload, and more. CAPTAIN and SKIPPER. See docs/BUTTONS.md
Tuning (`host/src/shaping.cpp`, `resonance.cpp`, `bedmesh.cpp`, `machine_pro.cpp`; Tune page)	Built and PC-tested; the shaping and pressure-advance maths timed on the ESP32 (2026-10-29), not yet used on a moving printer (2026-10-24): input shaping, pressure advance, accelerometer search and shaper calibration (matches Klipper's), bed mesh, screw tilt, arcs, G10/G11, exclude object, tuning tower. USB accelerometer: compile-only. CAPTAIN and SKIPPER only. See docs/TUNING.md
Little OLED display (`firmware/esp32s3/main/oled.cpp`, `components/ktft_oled`)	Works on hardware (2026-10-26: temperatures and the shutdown screen on a 0.96" OLED in the Tina 2); built 2026-10-23: SSD1306 / SSD1315 / SH1106, 128x64 or 128x32, on GPIO8/9: temperatures, progress bar, HEATING / HOMING / EXTRUDING / LOADING, "no board" with the WiFi name and password. See docs/OLED.md
Three builds by board memory: DECKHAND / CAPTAIN / SKIPPER (docs/TIERS.md), Flasher "Flash for my board"	CAPTAIN runs on hardware (2026-10-20: picked by the Flasher, 2 MB PSRAM found and used); WiFi firmware updates work (2026-10-20); the important-events log works (2026-10-28); not yet tried there: bigger look-ahead with PSRAM, slicer upload (OctoPrint-style), home WiFi, thumbnails, print history, event log, printer.cfg backups, crash reports
Print benchmark, motion benchmark, INT32/64 test build (docs/BENCHMARK.md)	On hardware (2026-10-28/29): both benchmarks run to the end on the Tina 2 with the SKR Pico and the drivers off; results in the important-events log. The integer build has not moved motors yet
Fans	Hotend fan confirmed on hardware; part-cooling fan and the third fan output not yet (possibly a broken wire, will update when tested)

Total checks: 1,825 C++ unit checks (run twice: with double and with integer motion maths), the OLED layout tests and 192 Python tests (including power-cycle, stallGuard and printing runs against a simulated board), all passing in the sandbox. Passing tests mean the maths and bookkeeping are right, not that a printer will behave.

Screenshots

The GUI building the tools and running the unit tests:

Both screenshots use the simulated board, not real hardware.

Flash a board (Linux, macOS, Windows)

python3 flasher.py          (Windows: double-click Flasher.bat; macOS: Flasher.command)

You need Python 3.8+ with Tk (Linux: sudo apt install python3-tk; on Windows and macOS the installer from python.org includes Tk). No toolchain is needed: firmware for every board preset (five boards, plus a serial variant of the SKR Pico) ships in firmware/prebuilt/. Pick the Slave tab, choose your board, press Flash... and confirm. RP2040 boards: hold BOOTSEL while plugging in USB. STM32 boards such as the Creality 4.2.x: put the SD card in this computer, Browse to it, flash, then move the card to the printer and power-cycle it. AVR boards need avrdude installed. The Master tab flashes an ESP32-S3 with esptool (Install esptool, then Use shipped firmware, pick the port, Flash). The port box fills itself with the ESP32-S3's port when it can tell which one it is (otherwise pick it). The shipped image starts a WiFi network SkipperFlipper-XXXX (WPA2, default password skipperflipper, change it before real use) with a page at http://192.168.4.1/, a live log at /console and printer.cfg at /config; it talks Klipper to the printer board over UART (identify, clock sync, printer.cfg, heaters, TMC2209 drivers, motor tests at /test, homing and running a print file from the Printer page: all on hardware with the SKR Pico; a real printed part not yet). Logs appear on the chip's native USB port. ESP32-S3 only: other ESP32 chips (original, S2, C3) are not supported, and esptool refuses to write if it finds a different chip. You can also flash your own .bin. To connect the ESP32-S3 to an SKR Pico with four jumper wires, see docs/WIRING_SKR_PICO.md.

Only the skr-pico-uart firmware (SKR Pico) has run on a board, where it has done everything above; the other presets have never been flashed. Read docs/FIRMWARE.md first, and do not flash a printer you cannot recover.

Quick start (Linux Mint / Ubuntu / Debian)

git clone https://github.com/The-Dorkknight/esp-printhost
cd esp-printhost
sudo python3 printhost.py

That one command installs what is missing (build tools, cmake, zlib, python3-tk, acl), gives you access to USB serial ports without logging out, stops ModemManager and brltty from grabbing printer boards, builds mcu_probe, runs the tests, and opens the GUI as your normal user. It is safe to re-run. HOW_IT_WORKS.md lists exactly what it changes on your system.

Options: --check (report only, change nothing), --no-gui, --clean, --yes, --version.

If anything fails it prints the path of a log file in ~/esp-printhost-logs/. Attach that when you open an issue.

macOS: the C++ library and tests build (python3 host/tools/build.py), but mcu_probe is Linux-only (it uses Linux's termios2 for 250000 baud) and the one-command setup is Linux-only.

Using the GUI

Build tools compiles everything and runs the unit tests. Output is colour-coded per tool.
Fake MCU: Start runs a pretend Klipper board (no hardware). Its port appears in the Port box.
Run probe connects, reads the board's pin list into the Blink pin dropdown, and prints uptime and state. Tick Blink pin and pick a pin to also toggle it 10 times.
The output box is selectable (Ctrl+C, right-click, Copy all, Save as...). Everything is also logged to ~/esp-printhost-logs/.

Try it without hardware

python3 host/tools/fake_mcu.py            # prints /dev/pts/N
./host/build/mcu_probe /dev/pts/N 250000 --pins --blink PA5

Try it on a real board

You need a board running stock Klipper MCU firmware (the Flasher ships plain Klipper v0.13.0 builds in firmware/prebuilt/, or build your own with the Firmware tab). Stop Klipper or anything else using the port, then:

./host/build/mcu_probe /dev/serial/by-id/<your-board> 250000 --pins --blink <pin>

--pins lists the pin names the board accepts. The probe validates your pin name before touching the board, and if the board is already configured it resets it first (the USB device re-appears after about two seconds). Do not run it on a board that is in the middle of a print.

Tested so far: BTT SKR Pico (RP2040, Klipper v0.10.0-181). The probe identified it, read 31 pin names, reset it, configured gpio24 and sent 10 toggles with 0 CRC errors.

Known limitations

It has not printed a real part yet. Homing and a whole print file have run on the Tina 2, but in mid-air: first layer, Z offset, extrusion and cooling are untested in practice.
Heaters: stay with the printer. Klipper's heater safety is ported and has shut the board down correctly on hardware ("ADC out of range"), but this is experimental firmware: keep a hand near the power switch and never leave it running unattended.
The tuning features have not moved a printer: input shaping, pressure advance, accelerometer calibration, bed mesh, screw tilt, arcs, firmware retraction, exclude object and tuning tower are built and PC-tested; the shaping maths has been timed on the ESP32, nothing more.
The INT32/64 test build has passed the PC tests (within one step of the double maths everywhere) and both benchmarks on the ESP32, but has not driven motors with its integer shaper yet.
Sending waits for the board: about 30 % of one core in the print benchmark is the ESP32 waiting for the SKR Pico's acknowledgements, where Klipper keeps sending. Fine at the Tina 2's speeds; it is the next speed work.
Delta is untested on a real printer and has no calibration (DELTA_CALIBRATE); the DECKHAND delta image is a separate build and its flash size is not measured.
The Pasta Inspector dongle link is untested: the websocket server has not been built with ESP-IDF or run against a real ESP32-CAM; CAPTAIN and SKIPPER only.
Only the SKR Pico has run. The other board presets are compile-only, and their bootloader details are assumptions. Small 8-bit boards give Klipper a much smaller move queue than the SKR Pico's 1,024 commands; this host has not been tried with one.
Flash is nearly full on DECKHAND (about 6 KB free) and CAPTAIN (about 14 KB); new features may need something trimmed.
The part-cooling fan and the third fan output are not confirmed (possibly a broken wire). The cause of one early SKR Pico lock-up after a shutdown (2026-10-13) is still unknown.
mcu_probe is Linux-only.
The GitHub workflows in .github/workflows/ have not been checked for this release.
Presets for boards with clone chips (some Creality 4.2.x) are flagged unverified; check your chip.
Design documents describe intent, not finished work.

Project layout

printhost.py          one-command setup + launcher
flasher.py            the Flasher window (also Flasher.bat / Flasher.command)
HOW_IT_WORKS.md       what it reads, changes and never does
docs/                 DESIGN, PROTOCOL, ENGINE, FIRMWARE, TUNING, TASKS, project page
firmware/esp32s3/       ESP32-S3 firmware (ESP-IDF project) + build.sh
firmware/prebuilt-esp32s3/  shipped ESP32-S3 images (DECKHAND / CAPTAIN / SKIPPER; test-int32/ for the INT32/64 test build)
firmware/boards/      board presets (.config + .json)
firmware/prebuilt/    shipped plain-Klipper firmware per board (+ pin tables); refresh with skipper_fw.py bundle
host/                 portable C++17 core (the same code runs on the PC and, as an ESP-IDF component, on the ESP32-S3)
  include/ph/         wire, msgproto, json_mini, config_ini, gcode, motion, planner, engine
  src/  test/         implementation + 1,825 unit checks
  tools/              build.py, skipper_fw.py, printhost_gui.py (+ fw_panel, skipper_theme),
                      mcu_probe.cpp, fake_mcu.py

Roadmap

See docs/TASKS.md. Next, in order:

Make the integer input shaper the standard in every build (keeping the double planner), now that it measures about 3.7 times faster on the ESP32.
Send without waiting for each acknowledgement, the way Klipper does, to win back most of the 30 % of a core spent waiting.
Move to the QIDI X-Smart 3 test bench and print a first real part.
Try the tuning features (input shaping, pressure advance, bed mesh) on a moving printer.

The look is a 1928 black-and-white cartoon (visuals only).

Source code: The-Dorkknight/esp-printhost on GitHub

SoloTrace

Matthew Armstrong — Sat, 31 Oct 2026 18:12:19 +0000

An easy PCB designer for single-sided, through-hole, quick-prototype boards. A small library of real full-size parts, traces up to 10 mm wide set with a slider, every corner chamfered (no pure 90° traces), an autorouter that avoids the "tangled string" look, and output for printing (toner transfer), Gerber fabs and a gantry diode laser (Elegoo Phecda) with a negative option and adjustable trace gap.

What exists and what does not

Area	Status
Place, wire, trace, trim and jumper tools, undo/redo, pan/zoom, flip view	Works in tests and the screenshots; lightly tested by hand
Right-click menus (trim, split, tidy, width, rotate, duplicate, wire from a pin, route one net...)	Works in tests and the screenshots
Rigid wires (Shift + Wire): a direct power trunk that the rest of the net branches off	Works in tests and on the demo; first suggested from real use
Auto-route retries (best of up to 6 net orders), jumpers optional globally or per net	Works on the test boards; slower (up to about 12 s plus one try)
Cut tool: one click removes a piece of trace from joint to joint (Shift: between two points)	Works in tests
Favourites & recently placed parts; Shift + click turns a part while placing	Works in tests
Branches stay joined when a trunk is widened, tidied or dragged; DRC warns about hanging trace ends	Works in tests and on rebuilds of real boards
Board > Keep traces out from under parts	Works on the test boards; can add jumpers on cramped boards
Pin labels (B C E, G D S, K A, IN GND OUT, optocoupler and DIP layouts) and part values on the board	Works; layouts are the common ones for each shape, check your datasheet
Dragging a trace section sideways (neighbours follow, 45° rules kept)	Works in tests; lightly tested by hand
90 through-hole parts in a form-factor tree with a live preview, footprint wizard, KiCad `.kicad_mod` import	Works; some parts excluded on purpose (see below)
Trace width slider 0.4–10 mm (segment, trace or net) + current readout + "fits up to" hint	Works
Wide traces leave pads straight and end on the pad centre (auto-tidy)	Works on the test boards; may leave a trace as it was when the tidy shape does not fit
Deadbug (surface-solder, no-drill) pads, per part or per pad	Works
Copper islands (Island tool): round or rectangular pads you drop, drag and resize; pins on an island join it	Works in tests and the screenshots; new in 0.4.0, not yet used on a real board
Ground fill for RF / Manhattan boards: the board is ground copper with a gap round every other net, floating fill removed	Works in tests, the examples and an independent Gerber reader; new in 0.4.0, never etched yet
Chamfered corners everywhere + DRC	Works
Auto-place and auto-route with jumper fallback	Works on the three demo boards and random test boards; pure Python, can be slow on big boards
Gerber + drill zip, 1:1 PDF/SVG, BOM CSV, netlist text	Written and re-read by an independent Gerber library in tests; not opened in a fab's own viewer
Laser G-code (negative / isolation / positive, test cards, frame file)	Geometry checked in tests; never run on a real Elegoo Phecda
Windows and macOS launchers, GitHub workflows	Not run (written but untested on those systems)
Floating slider pop-up beside the cursor	Not built: the slider is in the right-hand panel
Full PathFinder-style negotiated routing, topological router, C++ speed-up	Not built (see DESIGN_NOTES.md)
Soldermask and copper-pour layers, multi-layer boards, SMD	Out of scope

Quick tour: your first board in 5 minutes

File > Open example > 555 LED flasher (or File > New board and set a size).
Place parts: pick from Favourites & recent at the top of the parts panel, or open a group in the parts panel on the left (the little arrows show the sub-types, such as Resistors standing), pick a part, check the drawing under the list, then click on the board. Or type in the search box (dip 8, to-220, standing). R or Shift + click turns the part, Esc stops placing. Star parts you use a lot with the button under the preview.
Wire: press W, click one pin, then another (or drag from pin to pin). A yellow rubber-band line shows the connection. Hold Shift for a rigid wire (see below). Click a rubber-band line to name its net or give it a class (Signal 0.8 mm, Power 2 mm, High current 5 mm; change them in Board > Board size and rules).
Auto-place, then Auto-route (toolbar). A progress bar with Cancel shows while it works. Routes use 0°, 45° and 90° moves, and a 90° turn is always built as two 45° turns (a chamfer). If a trace can't get through, a wire-link jumper (blue dashed) is added on the component side.
Label: select a part and type its Value / type (NE555, BC547, 10k...), and pick its Pin labels (B C E, G D S, IN GND OUT...).
Tweak: drag a trace section sideways to move it, use Trim (X) to cut a section out, and right-click anything for its menu.
Check, then Export.

Quick and dirty RF (Manhattan / deadbug): File > Open example > Manhattan RF amplifier (copper islands). Press I and click to drop copper islands, sit the parts' pins on them, and tick Board > Ground fill. No traces needed.

Feature by feature

Library and parts. 90 parts, sorted by shape (form factor) rather than by maker code. Each group has an arrow that opens its sub-types:

Group	Sub-types
Chips (DIP)	Narrow (7.62 mm rows) DIP-4 to DIP-28, wide (15.24 mm rows) DIP-28 and DIP-40
Transistors & regulators	TO-92, TO-220 (2-pin, 3-pin, with heatsink outline), TO-247 / TO-3P
Resistors, diodes & inductors	Resistors lying flat (1/4 W to 5 W), resistors standing (1/4 W at 2.54 and 5.08 mm, 1/2 W and 1 W at 5.08 mm), diodes lying flat and standing, axial and radial inductors
Capacitors	Ceramic disc, film / box, electrolytic
LEDs	3 mm and 5 mm
Pots, switches & crystals	Inline pots (2.54 and 5.08 mm), triangle trimmer, 6 mm tactile switch, HC-49 crystal
Connectors	Pin headers 1-row and 2-row, screw terminals, JST-XH
Board bits	Wire links, mounting holes, solder and surface pads
My parts	Parts you made or imported

Click a part and a drawing of it (copper, holes, outline, pin numbers, pitch and drill) appears under the list, in the sidebar, with no pop-up. Names say what the part is ("Electrolytic cap, 5 mm pitch"), not an obscure model number. Left out on purpose because their sizes vary too much between makers: relay, USB-B, barrel jack, buzzer, fuse holder, panel pots with lugs, TO-126, bridge rectifiers. Make those with the wizard. Body outlines, the inductor, pot and trimmer layouts, and the standing-part pitches are generic: check them against your real part.

Your own parts. Parts > New footprint... opens the wizard: type a pad table (name, x, y, pad size, drill), or click on the canvas to drop pads, or start from a DIP or header preset, then save. Saved parts live in ~/.solotrace/parts (Parts > Open my parts folder). Parts > Import KiCad .kicad_mod... reads the text format of a KiCad footprint (through-hole pads and silkscreen lines only).

Trace width. Press T and click along the board to draw a trace (Enter, a double-click or Finish trace here on the right-click menu finishes it; corners are chamfered for you). To change a width, click a trace section on the drawing, or click a yellow rubber-band line to set the width of a whole net, then drag the slider in the right panel (0.4–10 mm; preset buttons 0.4, 0.8, 1.5, 2.5, 5, 10). Choose whether it applies to the section, the whole trace or the whole net. The panel shows roughly how many amps that width carries (IPC-2221 outer-layer formula; board settings give copper weight and temperature rise; a guide only) and how wide the trace can go where it is before it breaks the clearance rule.

Rigid wires (power trunks). A net with more than two pins is normally routed by joining the nearest pins first, so a ground net can end up as one long chain (transistor to capacitor to terminal). If you want a direct trace between two particular pins, hold Shift while wiring them (click or drag), or right-click a pin > Rigid wire from this pin, or right-click an existing rubber band > Make ... rigid. The router routes every rigid pair first, as its own pin-to-pin trace, then connects the rest of the net to the nearest point of that trunk, so a capacitor becomes a short branch. "Rigid" fixes which two pins are joined, not the path: the trunk bends round other parts like any trace, can be moved by a re-route, and you can drag or cut it. Rigid rubber bands are thicker and orange. Once routed, the trunk is drawn in the same copper colour as everything else, so joints look like the one piece of copper they will be, with a thin dashed orange line down its middle to show it is a rigid wire. Branches stop inside the trunk instead of poking out of its far side, and when you drag a trunk sideways the branches joined to it move with it and stay joined. The net panel lists the rigid pairs, each with a make normal button.

Copper islands (Island tool, I). Free-standing pads for Manhattan / deadbug building. Click on the board to drop one (5.08 mm square to start), or drag to draw one any size; Shift + click switches new islands between rectangular and round. With Select, drag an island to move it (0.635 mm steps, so it can sit under pins) and drag one of its white corner squares to resize it while the opposite corner stays put. The right panel takes an exact width, height and corner cut (rectangles get 45 degree corners like everything else; a round island with a different width and height is an oval), offers square/circle sizes from 2.54 to 15.24 mm, and has Turn 90, Duplicate (Ctrl+D) and Delete; arrow keys nudge it. Right-click an island for the same choices, or right-click empty board > Add a copper island here.

An island has no net of its own: it joins the net of whatever touches it, a pin, a trace or a jumper pad, and islands that touch each other share a net. So sit a part's pins on islands (deadbug pads make that easy) and the connection is made, with no trace. The panel says which net an island is on and which pins sit on it. If pins of two different nets end up on one island, that is a short and Check reports it. The router treats islands as copper and routes round them, and they appear in every export.

Ground fill (Board > Ground fill). For quick and dirty RF and fast analogue: the whole board becomes copper, used as ground, and every other net is cut free from it with a gap. Settings are under Board > Ground fill settings...:

Ground net: guessed (a net called GND, 0V, VSS, ground... otherwise the net with the most pins), or pick one; the net panel also has Use this net as the ground fill. The ground net is joined by the fill, so Auto-route does not route it, and its old automatic traces are removed when you turn the fill on.
Gap round everything else (default 0.6 mm, never less than the board's copper-to-copper gap). For laser etching keep it at least 3 to 4 line intervals.
Fatten other nets' copper by up to this much (default 1 mm): routed traces and pads grow into wide, low-inductance patches, but only where that keeps the gap from other nets, ground copper and the board edge. Copper islands you placed keep their size.
Remove floating fill (on by default): a piece of fill that no ground pin sits on, boxed in by other nets, is cut away rather than left as floating copper. A ground pin that sits on a piece of fill cut off from the rest gets a yellow rubber band; join it with a trace or a jumper.
Turning the fill on offers to make every pad a deadbug pad, since such boards are usually built with the parts soldered straight onto the copper.

The fill is drawn in the editor and is in the Gerber, the PDF/SVG prints and the laser G-code. In negative laser mode the laser then burns only the gaps (much faster); isolation mode burns the same thing on such a board.

Values and pin labels. Select a part: Value / type at the top of the right panel takes anything (NE555, BC547, IRF540, 7805, 10k, 100uF 25V) and is shown next to the part name on the board; double-click a part to jump to it. Pin labels offers the common layouts for that shape, not specific part numbers:

Shape	Layouts offered
TO-92	E B C, C B E, B C E, D G S, G D S, S G D, small regulator OUT GND IN / IN GND OUT
TO-220 3-pin	power transistor B C E, MOSFET G D S, IGBT G C E, regulator IN GND OUT, adjustable regulator ADJ OUT IN, negative regulator GND IN OUT, triac MT1 MT2 G, dual diode A K A
TO-220 2-pin	diode K A / A K
TO-247	G D S, G C E, B C E
DIP-4 / DIP-6	optocoupler A K E C; optocoupler with base pin; opto-triac
DIP-8	555-style timer, dual op-amp, single op-amp, dual optocoupler
DIP-14 / 16 / 20	logic GND and VCC pins; quad op-amp (DIP-14)
Pots, connectors	1 W 3, CCW W CW; + -, - +, AC AC, IN OUT, V+ GND V-, IN GND OUT

Or type your own in pin order, separated by spaces (. skips a pin). Diodes and LEDs show K A, electrolytics + -, without asking. Pin orders differ between makers, so always check the datasheet of the part you have. Labels are shown in the editor; they are not yet written into the Gerber silkscreen.

Wide traces are tidied. When a trace is 1.2 mm or wider, SoloTrace makes it leave each pad with a straight vertical or horizontal run (about the pad radius plus the trace width) before it turns, ends it exactly on the pad centre, and makes the chamfers bigger where there is room. This happens after auto-routing and, with Auto-tidy when the width changes ticked (the default), whenever you change a width. If the tidier shape would touch other copper the trace is left as it was, and the clearance problem is marked in red. Tidy (right panel or right-click) does it on demand; Edit > Tidy all traces does the whole board.

Cutting a piece out of a trace. Press C and click a trace: the piece under the mouse goes, from the joint before it to the joint after it (a pad, a place where another trace meets it, a jumper pad). The rest of the trace and of the net stays. While you hover, the piece that would go is shown in red. Right-clicking a trace only opens its menu; rest the mouse on Cut this piece to see the piece in red, and choose it to remove it. To cut between two points of your own choosing, Shift + click the first point and Shift + click the second (or right-click > Cut between two points); Esc cancels.

Moving, trimming and splitting traces. With Select, drag a trace section sideways: it moves parallel to itself and the sections either side stretch to follow at their own angle, so no 90° corner appears. Ends on pads stay put (a 45° link is added). Trim (X, or right-click > Trim this section) cuts one section out and leaves the rest as separate pieces; Split trace here breaks a trace in two without removing copper. A trace you have moved or trimmed counts as hand-drawn, so Auto-route keeps it. Ctrl+Z undoes any of this.

Right-click menus. Right-click (without dragging) on a trace, pin, part, rubber-band line, jumper or empty board for the actions that fit: widths, trim, split, tidy, highlight or re-route the net, rotate either way, duplicate, lock, pad styles, wire or trace from a pin, disconnect, delete, and Undo/Redo. Right-drag still pans.

Small helpers. Hover over copper to light up its whole net (the net name shows in the corner). Arrow keys nudge the selected part by 1.27 mm (Shift: 2.54 mm), Ctrl+D duplicates it, Shift+R turns it back. File > Open recent lists your last boards. While a board has unsaved changes it is saved every 2 minutes to ~/.solotrace/autosave.solotrace; File > Recover autosave opens it (the file is removed when you quit normally). Hover over a toolbar button for a hint. The status bar shows the cursor position in mm and a green all routed or orange N to route badge.

Pads: through-hole or deadbug. Pick Through-hole, Deadbug or Both in the toolbar for new parts, or change it for a placed part in the right panel, or for one pad ("This pad only"). Deadbug pads have no hole and are drawn as a long oval that sticks out from the part so you can bend the lead flat and solder it on the copper side. "Both" keeps the hole and the extra copper.

Auto-place. Simulated annealing that moves, rotates and swaps unlocked parts to shorten the ratsnest and cut crossings. Tick Lock on a part to keep it where it is.

Auto-route. A grid router that remembers its heading, so it prefers straight runs and clean 45° bends instead of staircases. Wide nets are routed first, and it prefers not to run under part bodies. If a net is blocked it tears up the nets in the way and retries; as a last resort it adds a jumper, unless you unticked Jumpers in the tool bar or for that net. The whole job is tried with up to six different net orders (about 12 seconds at most, plus the try in progress) and the best result is kept; it stops early when a try routes everything without jumpers. Traces you drew by hand are kept. Board > Remove automatic routes undoes only the automatic ones.

Jumpers. Press J to add one by hand. They are plain wire links on the component side, in 2.54 mm steps from 5.08 mm. They are listed in the DRC window.

View. M flips between the component side (how you place parts) and the copper side (how the etched board looks from below). Wheel zooms, right or middle drag pans, right-click opens the menu, F fits the board.

DRC. Check lists trace ends that are not joined to anything ("dangling"), copper too close to other copper or the board edge, parts sticking out of the board, traces thinner than the minimum, turns sharper than 45°, drilled pads with too little copper ring, jumpers that are the wrong length or cross each other, and pins that are not connected yet. Click a row to jump to it on the board.

Exports (Export menu).

Output	Use
Gerber + drill (zip)	Copper (bottom), board edge, silkscreen, Excellon drill. Single layer; no soldermask layer
1:1 PDF / SVG, mirrored	Toner transfer or photo-resist film: the copper side as you will see it. Always print at 100 % and measure a known distance before etching
1:1 PDF, design view	Component-side print
Bill of materials (CSV)	Parts grouped by name and value
Netlist text	Round-trip text format for a quick board from a text editor
Laser G-code (Elegoo Phecda)	See below

Laser etching with the Elegoo Phecda (gantry diode laser)

Read this first. A diode laser cannot remove bare copper. The method is: paint the copper, let the laser burn the paint away where copper must go, etch, then clean the paint off. Nobody has run these files on a Phecda yet. Treat every default as a starting guess and use the test cards.

Finish the board and run DRC. Open Export > Laser G-code (Elegoo Phecda)...
Mode
- Negative (default): burns everything that is not copper, so paint is left only on the traces and pads. Slowest, cleanest.
- Isolation: burns only a band of gap mm around the copper. Fast; leftover paint between bands must be cleared by hand or by the etchant.
- Positive: burns the copper shapes themselves (for a negative-working resist or marking).
Adjust (all live-previewed):
- Trace adjust (mm per side): positive grows the copper, negative thins it and widens every gap between traces. Use this to correct for the laser's spot size and your etch.
- Gap (isolation band width) and Border (keep paint at the board edge).
- Line interval (default 0.08 mm; the module's spot is about 0.06–0.13 mm depending on model), feed (default 1500 mm/min), power (default 70 % of S max), passes, crosshatch (second pass at 90°), bidirectional scanning, M4 dynamic power (default) or M3 with overscan, and drill dots (a tiny burn at every hole centre as a drilling guide).
Click Save G-code.... Also use Frame file... (traces the board outline at 1 % power so you can line up the paint) and, on first use, Speed/power test... and Trace/gap test... (a grid of squares and a ladder of fine traces and gaps).
In LaserGRBL or LightBurn: jog the laser to the lower-left corner of the board as seen from the copper side, set work zero there, open the file, check the preview, run the frame, then burn. The exporter mirrors X for you because the design view is the component side.
Controller assumptions: GRBL-style, $30 equal to the S max in the dialog (default 1000) and $32=1 (laser mode). The Elegoo manual names LaserGRBL and LightBurn but does not say "GRBL"; see docs/research/phecda-laser-notes.md.

Examples to look at without installing anything: examples/ has four boards, each with its .solotrace file, Gerber zip, 1:1 copper-side SVG and PDF, BOM and laser G-code in both modes, plus test cards.

HOW_IT_WORKS.md: what it reads and writes, the coordinates, the router and the laser engine in plain English
DESIGN_NOTES.md: decisions, rejected ideas, measurements, what is untested
docs/research/: the original research and plan, and the Phecda notes
CHANGELOG.md · CONTRIBUTING.md · SECURITY.md

Project page (after you enable GitHub Pages): https://The-Dorkknight.github.io/solotrace/

Source code: The-Dorkknight/solotrace on GitHub

A POINT of contention

Matthew Armstrong — Tue, 20 Oct 2026 14:43:06 +0000

STL to STEP conversion shouldn't be that HARD: a proposed hybrid STL format that is CAD-friendly and slicer-compatible

Converting an STL back to a STEP file means guessing the original CAD faces. This paper proposes a normal binary STL that also records them, so slicers still open it and converters no longer have to guess. It is also a public, dated description of the format, and a list of the ideas that didn't work.

Matthew Armstrong · GitHub The-Dorkknight · United Kingdom\
First published 15 October 2026 · Version 1.0\
Text and figures: CC BY-SA 4.0. Code that comes with it: PolyForm Noncommercial 1.0.0.

📄 PDF · 🌐 Web page · 🔧 The FreeCAD and Fusion plug-ins · About this repository

This page is the full paper (the same text and figures as the PDF).

Contents: Abstract · Why I wrote this · The problem: what STL loses, and how slicers read it · Prior art: what I found (3–10 October 2026) · How the idea was judged · The ideas that didn't work · The format, in one picture · Does it help? · What works, and what doesn't yet · Defensive disclosure: the hardpoint STL and variations · What I'd test next (feel free to use this plan) · Working together · How this was made · Code, data and how to reproduce · Licence, and keeping it free · Disclaimers · How to cite · References · Appendix A: a real hardpoint STL

Status: nothing in this paper has been run in real FreeCAD, in Fusion, or in a slicer. The format and its reference code were tested on Linux, using test parts built with OpenCASCADE and the file-reading code that slicers use (not the slicers themselves). The FreeCAD and Fusion exporters were only tested against stand-ins for those programs. The conversion results come from one converter of mine. If you open the example files in your slicer before I do, please tell me what happened.

Not legal advice. I am not a lawyer. Where this paper talks about prior art, it says what I found, where I found it, and when. A patent attorney is the person to ask about what it means.

Plain STL: 1,103 faces	Hardpoint STL: 8 faces

The same knob, made from the same triangles, converted to STEP. Left: from a plain STL, which came out with 1,103 faces. Right: from the hardpoint version of the file, which came out with 8 faces. The original CAD model has 4.

Abstract

An STL file is just a pile of triangles. It has lost everything the CAD program knew: which triangles made up one flat face, which made up a round hole, and where the corners were. Turning an STL back into a real CAD solid means guessing all of that again, and the guesses go wrong most often on coarse meshes and curved edges.

This paper describes a way to keep that information in the file without breaking it for anyone else:

The idea: write the CAD facts into the two places a binary STL already has spare room that slicers ignore: the 80-byte header, and the 2-byte "attribute" field after every triangle.
What goes in: which face each triangle belongs to (as a small colour number, like colouring a map so that neighbouring areas differ), what kind of surface the face is, and which triangle corners are CAD vertices ("hardpoints"). A checksum in the header shows whether the mesh was edited afterwards.
What a slicer sees: the same triangles, the same file size, the same .stl extension.
How much it helps: in my tests, a converter given the labelled file turned a knob into a STEP solid with 8 faces. From the same triangles without labels it made 1,103 faces (the original CAD model has 4). On a clean, fine bracket the gain was small: 21 faces down to 17, against 16 in the original.
What didn't work: data after the last triangle, a 9-bit face number, hiding the whole STEP file inside the STL, remembering how freeform faces were cut up, and a handful of mistakes along the way.

Section 8 describes the format and its variations in enough detail to build them. It is written as prior art, so the method stays free for everyone to use.

0. Why I wrote this

How it started:

I convert STL files into STEP files. Most of the converter's effort goes on working out again what the CAD program already knew.
The CAD program could say it at the moment it writes the STL. Instead it throws the answer away.
A binary STL has two spare places that slicers ignore. I'm a hobbyist in the UK with a laptop, and I wanted to see if the answer could be kept there.

So I built the hardpoint STL, plus an exporter for FreeCAD and one for Fusion. First I researched how slicers read STL files. Then I tried to find every way a file like this could break them.

Why publish all of this, including the failures? Four reasons:

Protection. I looked, and found no earlier description of putting CAD face labels inside an STL (section 2). If that is right, a dated, detailed public description is a cheap way to keep the idea free for hobbyists. That is what a defensive publication is.
Saving you time. Every dead end here is one you don't have to walk down. The best one began as a question of mine that turned out to have a simple numerical answer (section 4.3).
Getting other people involved. The format has room for more exporters (CadQuery, Onshape, SolidWorks) and more readers than I can write.
Selfishly: by my calculations, a third paper makes me about 0.7 % more employable. The first was worth 22.7 % and the second 3.14 %, so the returns are falling. That's probably fine. Publish too many and I start to look like I have a lot of free time, and nobody wants to hire someone who looks that available.

How this was made. The ideas, the questions and the rules are mine. The code, the tests, the measurements and the first draft of this write-up were done with an AI assistant (Claude, by Anthropic), working to my design. All sources are linked so you can check them, and the code is included so you can re-run every number that can be re-run (section 12).

1. The problem: what STL loses, and how slicers read it

1.1 What gets lost

A CAD solid is made of faces: planes, cylinders, spheres, cones, tori and freeform surfaces, joined along edges and corners. Exporting it as STL cuts every face into triangles and writes only the triangles. A flat face and a rounded edge of the same bracket both end up as nothing but triangles.

A mesh-to-CAD converter has to work out again which triangles form one flat face (and how flat is flat enough?) and which form a curve. When the mesh is coarse, or a curve meets a flat face very gently, it can't always tell.

1.2 What I set myself

The design had to meet six requirements, in this order:

Recognised as an STL. The extension stays .stl and the file loads in any slicer without a plug-in.
Identical to a normal STL in a slicer. Same triangles, same file size, nothing a slicer acts on.
Makes STL-to-STEP conversion easier. It carries what a converter otherwise guesses: faces, surface types, corners.
Writable from inside CAD programs. FreeCAD's and Fusion's own Python can't be assumed to have NumPy, so the writer uses the standard library only.
Never makes a conversion worse. Labels are hints. The reader checks each one.
Runs on low-end hardware. The target machine is a 7th-generation Core i3.

1.3 What STL readers do with a file

A binary STL has an 80-byte header, a 4-byte triangle count, then 50 bytes per triangle: 12 for the normal, 36 for three corners, and 2 for an "attribute byte count" that slicers ignore. So there are exactly two places that carry no meaning to a slicer. Anything after the last triangle is a different matter.

Reader	Used by	Binary or text test	Triangle count	Extra bytes at the end	How this is known
admesh `stlinit.cpp`	OrcaSlicer; PrusaSlicer-family slicers share this code	Binary if any of the 128 bytes after offset 84 is above 127	Taken from the file size; the header count only logs a warning	Rejected unless a multiple of 50, then read as phantom triangles	Read OrcaSlicer's source (PrusaSlicer's and Bambu Studio's copies not read)
numpy-stl	Cura, through Uranium's STLReader	Automatic mode	From the header	Load fails with an error	Read Uranium's source; ran the library
trimesh	many Python tools	Binary only if the size is exactly 84 + 50 × count, otherwise tried as text	From the header	Not binary, then fails as text (0 faces)	Read trimesh's source; ran the library

Other findings that shaped the format:

The admesh text test misreads simple files. A cube at whole-millimetre coordinates with zero normals has no byte above 127 in that window, so it is read as text and imports empty. This is OrcaSlicer issue 15993, open when I checked on 3 October 2026. A probe copying the test's logic reproduced it.
The header must not start with solid. Some software then treats the file as text (Wikipedia).
Two colour conventions already use the attribute field. VisCAM and SolidView: bits 0–4 blue, 5–9 green, 10–14 red, bit 15 = 1 means the colour is valid. Materialise Magics: a COLOR= string in the header, bits 0–4 red, 5–9 green, 10–14 blue, bit 15 = 0 means the triangle has its own colour (both as described on Wikipedia).
trimesh drops the attribute field during clean-up. With process=True it survives vertex merging, but removing sliver triangles rebuilds the mesh. On one test part 5,572 triangles became 5,564 and the field was gone.

2. Prior art: what I found (3–10 October 2026)

Using the attribute bytes of an STL for something other than "nothing" is old: the two colour conventions above are the best-known uses. What I looked for was a file that keeps CAD face identity, surface types and CAD vertices inside an ordinary STL.

I found no description of that. The searches were ordinary web and code searches by me and my AI assistant, over a few days. They are not a professional prior-art search, and a miss here proves little.
Existing mesh-to-STEP tools (stlToSolid, breptile) segment the mesh and fit primitives from the triangles alone. As far as I could tell neither reads hints from the file.
The standard container for "a mesh plus the real CAD in one file" is 3MF, which is a zip. It is not an STL, and I did not test how slicers treat an extra file inside one.

Whether any of this affects anyone's rights is a question for lawyers, not me.

3. How the idea was judged

I can't build exact CAD parts by hand, so I had a CAD kernel make them:

Test parts. Two parts built with OpenCASCADE (the kernel FreeCAD uses): a bracket (rounded corners, three holes, a boss, a countersink) and a knob (cylinder, sphere, torus fillet). The bracket was meshed at two settings.
Twin files. Each mesh was written twice with identical triangles: once labelled, once as a plain STL.
The converter. Both files went through STL2STEP, an earlier converter of mine (since superseded; its code is not in this repository), default settings. I counted the faces in the STEP result, the largest distance from the mesh, and the volume against the original CAD solid.
The format itself. Round trips (write, read back, compare faces, types and hardpoints), tamper checks, and the loaders of section 1.3.

What this gets wrong (please read before quoting a number):

Three test parts, built for the tests. No real downloaded models.
One converter. Another converter may use the labels better or worse.
Linux only. The writer was timed on a cloud machine, not on a Core i3.
The FreeCAD and Fusion code ran against stand-ins with the same attribute names, filled with OpenCASCADE geometry. That checks the plug-ins' own logic and nothing about how the real programs behave.

4. The ideas that didn't work

4.1 The table

Seven ideas were built or tested and then dropped. Each row says what the evidence was, so nobody repeats the experiment blind.

Idea	What happened	Evidence
Store extra data after the last triangle	Loaders fail or read garbage	numpy-stl raised an error, trimesh loaded 0 faces, admesh's logic reads phantom triangles
A global face number in 9 bits	Replaced by colours	Capped at 511 faces; colours need 2 to 5 values for any count
Hide the STEP file itself in the STL	It doesn't fit as text, and only sometimes when compressed	Section 4.3
Remember how a freeform face was cut into patches (a second, 3-bit "patch colour")	Faster but worse, so removed	Organic part: 83 s down to 19 s, but 20 areas left as facets instead of 2 and maximum deviation 0.16 mm instead of 0.12 mm
Let the converter's normal detection handle cone and torus faces	It chopped them into cylinder and sphere pieces	Knob: 131 STEP faces and 3 failed faces, against 8 faces when treated as freeform
Label a whole-body mesh by nearest triangle centre	Mislabelled triangles beside face borders	About 1 % wrong on the knob, which turned into 11 false flats and 315 STEP faces. Point-to-triangle distance gave 100 %
Carry the attribute field through trimesh's clean-up	Lost whenever slivers are removed	5,572 triangles became 5,564 with no attribute data. Matching by position replaced it

A likely reason saved patch layouts gave a worse result (not proven): the fit of a patch depends on its border curves, and the converter smooths those borders step by step over several passes. Starting from the final layout skips the steps that made it fit.

4.2 Mistakes along the way

These are in the order they happened. Most were the AI assistant's, and they were caught by tests I had asked for.

1. A missing triangle. The knob's sphere has a pole where one triangle collapses to a line once nearby points are welded. The writer rightly dropped it (1 of 2,959). The tests then compared labels with the wrong triangles, because the output order no longer matched the input. The encoder now reports which input triangle sits at each output position.

2. About 1 % of triangles mislabelled. Fusion's fallback labels a whole-body mesh from per-face meshes. First version: nearest triangle centre. It looked fine in a picture and mislabelled about 1 % of triangles beside face borders, which a converter read as 11 flat faces and 315 STEP faces. Point-to-triangle distance fixed it.

3. A flat disc shown as rough facets. The converter's preview showed the top of the bracket's boss as dark left-as-facets. The rule that called a planar face a facet was "three edges or fewer"; a flat disc bounded by one circle qualifies. It now also requires every edge to be straight.

4. A renamed OpenCASCADE method. The test code called TopoDS.Edge_s, which doesn't exist in the OCP 8 build installed. A small compatibility helper hides the difference.

5. A changelog that claimed too much. I compared my changelog with the public repository of the converter on the day I packaged it. Five bullets under the published version had been added after it was published. They moved to the new version's section.

6. Screenshots taken at the wrong moment. Two documentation screenshots showed a job queue card and a sandbox folder name. They were retaken in a clean state.

7. A plug-in never tried in its real program. I could not install FreeCAD where this was built: its release downloads, conda-forge, the Ubuntu package source, the PPA and Flathub were all blocked, and I did not route around the block. So the workbench ran only against stand-ins. In its place, tests/freecad_selfcheck.py runs inside the real program in a few seconds. It has not been run either. I keep repeating that because it is the most useful thing a reader could check.

4.3 Could the whole STEP file be hidden in the STL?

Partway through I asked: would it be easier to hide a STEP file inside the STL as plain text? It was worth checking, because it would give the exact CAD model back with no fitting at all.

It doesn't fit. The room in an STL grows with the triangle count (2 bytes each), while the size of a STEP file grows with the number of faces:

Part	STEP file	STEP compressed	Attribute room (2 bytes × triangles)
Bracket, 1,180 triangles at 0.05 mm	48.1 KB	6.6 KB	2.3 KB
Knob, 2,958 triangles	9.3 KB	2.1 KB	5.8 KB

Simple parts with big flat faces fit worst. A text (ASCII) STL has no comment syntax; from reading OrcaSlicer's reader, extra text lines inflate its triangle count and the load fails (read, not run). A compressed STEP would also need every attribute bit, including bit 15, and would compete with the labels for the same bytes. It could be an optional extra: store it when it fits, fall back to labels when it doesn't. That is a variation in section 8.6, not a result.

5. The format, in one picture

Drawn from the specification by tools/make_illustrations.py.

Header (80 bytes of ASCII, padded with spaces):

HARDPOINT-STL 1 u=mm tol=0.05 ang=15 crc=e67609a0 by=cad-example

Field	Meaning
`HARDPOINT-STL 1`	Marker and format version
`u`	Units: `mm`, `in`, `cm` or `m`
`tol`	How far triangles may be from the true surface, in those units; 0 = unknown
`ang`	Meshing or sharp-edge angle in degrees; 0 = unknown
`crc`	CRC-32 of the 48 geometry bytes (normal and corners) of every triangle, in file order
`by`	What wrote the file

Attribute field (16 bits per triangle, little-endian):

Bits	Meaning
0–4	Face colour, 0 to 31. Faces that touch along an edge never share a colour
5–6	Reserved, 0
7	1 = this triangle is labelled
8–10	Surface type: 0 unknown, 1 plane, 2 cylinder, 3 sphere, 4 cone, 5 torus, 6 freeform, 7 keep as facets
11–13	Hardpoint flags for corner 1, 2 and 3 of the triangle
14	Reserved, 0
15	Always 0 (some viewers read bit 15 = 1 as "this field is a colour")

The bracket example (examples/bracket_hardpoint.stl): 1,180 triangles, 16 faces labelled with 3 colours, 25 hardpoints. Drawn from the file itself.

Why these choices (every one follows from section 1.3 or from a measurement):

Question	Chosen	Rejected	Why
Where the labels live	Header and attribute fields	Data after the last triangle	A trailer fails in numpy-stl and trimesh and becomes phantom triangles in admesh
How a face is identified	A 5-bit colour; a face is the edge-connected triangles sharing it	A global face number	Colours label any number of faces. Test parts needed 2 to 5 colours
Surface parameters (plane, axis, radius)	Not stored; the reader fits them	A parameter table	No room without a trailer. Fitting is cheap once the faces are known, and a reader must verify anyway
CAD vertices	3 bits per triangle, one per corner	A separate vertex list	No room. Needed where only two faces meet but a line runs into an arc
Detecting edits	CRC-32 of the triangle data in the header	No check	Stale labels on an edited mesh would mislead the converter
"Labelled" flag	Bit 7, and a labelled triangle is written first	A separate guard	Bit 7 of the first attribute byte also defeats the admesh text misread
Bit 15	Always 0	Free use	VisCAM-style viewers read bit 15 = 1 as a colour
Trust	Every label is checked against tolerance	Believe the file	A wrong or stale label must not produce a wrong solid

6. Does it help?

Labels helped most on a coarse mesh and on a part with a sphere and a rounded edge. On a clean, fine mesh of flats and cylinders they changed little.

Volume error is the STEP solid against the original CAD solid (bracket 24,490.97 mm³, knob 12,347.01 mm³). Converter: STL2STEP 0.2.0-wip, Classic engine, default settings.

Part	Triangles	Plain: STEP faces	Plain: volume error	Plain: max deviation	Hardpoint: STEP faces	Hardpoint: volume error	Hardpoint: max deviation
Bracket, 0.05 mm mesh	1,180	21	−0.013 %	0.050 mm	17	+0.001 %	0.049 mm
Same bracket, coarse 0.3 mm mesh	578	90	−0.075 %	0.109 mm	29	+0.002 %	0.086 mm
Knob, 0.05 mm mesh	2,958	1,103	−0.18 %	0.129 mm	8	+0.007 %	0.060 mm

On the coarse bracket the plain conversion found 55 "flat" faces where the CAD model has 7.
On the knob, the plain conversion took 14 s and the labelled one 2 s. The converter's second engine showed the same pattern in face counts: 21 to 17, 125 to 17 and 77 to 8.
The CAD models have 16 faces (bracket) and 4 (knob), so even with labels the converter returns slightly more than the original. Cone and torus faces are labelled but the converter fits them as freeform surfaces.

The knob in the converter's own 3D preview, from the plain STL and from its hardpoint twin (same triangles; blue = flat, green = cylinder or sphere, grey = freeform surface, dark = left as facets):

Plain STL: 1,103 faces	Hardpoint STL: 8 faces

Other measurements:

Colours needed: 2 on the knob, 3 on the bracket's 16 faces, 5 on an organic part's 69 fitted regions.
Round trip: the reference reader rebuilt exactly the faces, types and hardpoints written, on all three parts (25 of 25 and 4 of 4 CAD vertices).
Loaders: numpy-stl returned triangles identical to the plain twin; trimesh loaded each file as watertight; the admesh text test classed each as binary.
Plain inputs unchanged: five parts on the Classic engine and four on the second engine gave the same face counts, deviation and volume as before the feature was added.
Writer speed, pure Python: 4,894 triangles in 0.1 s and 15,384 in 0.2 s. The whole-body fallback added 0.4 s and 2.0 s. Measured on a cloud machine, not on a Core i3.

7. What works, and what doesn't yet

	Tested here	Simulation or stand-in only	Not tested / unknown
Format	Write, read, tamper check, `verify`, `strip`; examples pass
Loaders	numpy-stl, trimesh; admesh text test (logic copied from the source)		The slicer programs themselves
FreeCAD export		Logic against a stand-in filled with OpenCASCADE geometry	Real FreeCAD (0.20 to current); whether older versions accept the meshing call used
Fusion export		Per-face and whole-body routes against a stand-in	Real Fusion; whether per-face meshes close; winding on reversed faces
Converter	Three parts, two engines		Real downloaded models; large meshes (labels tested up to 5,120 triangles)
Systems	Linux		Windows, macOS
Colour-aware viewers			Whether a viewer using the Magics convention tints faces without `COLOR=` in the header

Known limits:

Any program that re-saves the STL writes its own header and zero attribute fields, so the labels vanish. That is also why the file falls back to a plain STL, which is the safe direction.
Text (ASCII) STL cannot carry labels.
More than 32 faces that all touch each other cannot be coloured; the writer refuses with an error. No test part has hit this.
Shapes with shared faces (FreeCAD compsolids) may give a segment count that differs from the face count; types are then written as unknown.
Fusion bodies inside occurrences are exported in their own component's coordinates, not the assembly's.

8. Defensive disclosure: the hardpoint STL and variations

This section is written to be prior art. It describes the method and its variations in enough detail for a person skilled in CAD programming and mesh file formats to build them. I dedicate the methods described in this paper to the public, and I will not seek patent protection for them. Where a variation is untested, it says so; untested variations are disclosed as possibilities, not as results.

8.1 The core method

A method of storing computer-aided-design face information in a triangle-mesh file in the binary STL format, such that the file remains a valid binary STL, comprising:

Keep the file a binary STL. Write an 80-byte header, a 4-byte little-endian triangle count, and for each triangle 50 bytes: a normal (3 × float32), three corners (9 × float32) and a 2-byte attribute word. The file size is exactly 84 + 50 × the triangle count. The geometry bytes are those a conventional export of the same mesh would give.
Put the file-level facts in the header. Begin the 80-byte header with an ASCII marker and a version number, followed by space-separated key=value fields: units, mesh tolerance, mesh angle, a checksum of the geometry bytes, and the writer's name. The header does not begin with the word solid. Readers ignore keys they do not know.
Put the per-triangle facts in the attribute word. For each triangle, store (a) a face colour in 5 bits, (b) a "labelled" flag, (c) a surface-type code in 3 bits, and (d) three bits flagging which of the triangle's three corners are CAD vertices (hardpoints). Leave remaining bits as reserved zeros, and keep the most significant bit zero.
Identify faces by colouring, not numbering. Assign each CAD face a colour so that any two faces whose triangles share an edge have different colours. A face is then recovered as a set of edge-connected triangles of equal colour. A small number of colours labels any number of faces.
Make labels checkable. The checksum covers the 48 geometry bytes of every triangle in file order, so a reader detects that the mesh was changed after labelling, and then treats the file as an unlabelled STL.
Make labels hints. A reader checks each labelled face against its own tolerance and falls back to unaided detection for any face that fails.

8.2 The reference writer (as built)

The reference writer is hstl.encode, about 100 lines of Python (standard library only), so it can run inside FreeCAD's and Fusion's own interpreters.

Round and weld. Round every coordinate to float32 (after an optional scale, e.g. ×10 for a program working in centimetres). Merge points closer than a welding tolerance, by default 2 × 10⁻⁷ of the part's bounding-box diagonal (at least 10⁻⁹). A CAD kernel gives the two faces along an edge points that differ in the last digits, so exact matching leaves the mesh open.
Drop collapsed triangles. A triangle with two corners welded together is left out, and the writer returns which input triangle each output position holds.
Check the mesh. Count edges used by one triangle (open) and edges used by more than two, or by two triangles in the same direction (bad). Report the mesh as watertight when there are none.
Colour the faces. Build a graph whose nodes are faces and whose edges join faces sharing a mesh edge. Colour it greedily in smallest-last order: repeatedly remove the node of lowest remaining degree, then assign colours in reverse removal order, each the smallest not used by a neighbour. Refuse, with an error, if 32 colours are not enough.
Flag the hardpoints. For each CAD vertex, find the welded mesh point nearest to it within 50 welding tolerances; set the flag bit of every triangle corner using that point. Report how many vertices found no point.
Put a labelled triangle first. Swap one labelled triangle into position 0. Its attribute word has bit 7 set, which makes the sniffing test of section 1.3 see a byte above 127 near the start.
Write the records. Recompute each normal from the welded corners as a unit vector. Pack the attribute word as (colour) | 0x80 | (surface type << 8) | (corner flags << 11). Triangles without a face get zero.
Checksum and header. CRC-32 over the 48 geometry bytes of every record in order; write the header with it.

8.3 The reference reader

Recognise. Read the 84-byte prefix. The file is a hardpoint STL if the header starts with the marker, the file size is 84 + 50 × count, and the version is known. Otherwise treat it as a plain STL.
Verify. Recompute the checksum. On a mismatch, ignore the labels.
Weld corners with identical float32 coordinates (a writer has already welded within tolerance, so exact matching suffices).
Group triangles that share an edge and have the same colour into faces. A triangle with the labelled flag clear belongs to no face.
Type each face by majority vote over its triangles' type codes.
Collect the corners flagged as hardpoints.

8.4 How a converter should use the labels

This is the behaviour of the converter I measured with, written as a recipe:

If the header gives units other than millimetres and the user did not choose units, use the file's.
Load and clean the mesh as usual. Skip labels if the mesh was reduced first.
Match each cleaned triangle to the file's nearest triangle centre. Require at least 98 % to match within 0.25 × the header tolerance, otherwise ignore the labels.
Handle each face by its type:

Label	Check	If it passes	If it fails
Plane	Least-squares plane; every corner within 1.5 × tolerance	A true plane	Unaided detection inside that face
Cylinder, sphere	The usual fit; if its sanity rules reject it, a least-squares fit of the labelled kind with every corner within tolerance	An analytic cylinder or sphere	Unaided detection inside that face
Cone, torus, freeform	None up front	Freeform patch fitting, without a search for primitives	The existing behaviour
Keep as facets	None	Kept as exact triangles
Unknown or unlabelled	None	Unaided detection inside that area

Map each hardpoint to the nearest mesh vertex within tolerance, and split border curves there, so a line running into an arc is fitted as a line and an arc.

The second cylinder check exists because the usual fit rejects shallow rounds, which it cannot tell from flat strips. A CAD label can.

8.5 Getting the labels out of CAD programs

	FreeCAD	Fusion
Mesh	One mesh of the whole shape with one segment per face: `MeshPart.meshFromShape(Shape, LinearDeflection, AngularDeflection, Relative=False, Segments=True)`	Each face meshed on its own through `face.meshManager.createMeshCalculator()`, with a surface tolerance (cm) and a maximum normal deviation (radians)
Triangle to face	Segment i is face i in explorer order (checked in FreeCAD's source)	Known by construction
Surface type	Class name of `face.Surface` (Plane, Cylinder, Sphere, Cone, Toroid; anything else freeform)	Last part of `face.geometry.objectType` (Plane, Cylinder, Sphere, Cone, Torus; anything else freeform)
Hardpoints	`shape.Vertexes`	`body.vertices`, each `.geometry`
Coordinates	mm; the object's global placement is applied	cm × 10; the body's own component coordinates
If something is off	Segment count differs from the face count: faces are still labelled, types are written as unknown	Per-face meshes don't close: mesh the whole body and give each triangle the face of the per-face triangle its middle point lies on

The whole-body fallback uses true point-to-triangle distance (nearest centre mislabelled about 1 %, section 4.2). It searches a uniform grid of cells, in growing shells, until the nearest triangle found is closer than the edge of the searched block.

FreeCAD's source shows that meshFromShape runs one incremental mesh over the whole shape, reads the triangulation back face by face in explorer order, flips reversed faces, and with Segments=True adds one segment per face. For Fusion, whether per-face meshes share identical points along a common edge is not stated in Autodesk's pages; the writer reports open and wrongly oriented edges and the add-in switches to the whole-body route when there are any.

8.6 Variations (disclosed; mostly untested)

Where the bits go

Use the reserved bits (5, 6 and 14) for: a "smooth border" flag for faces that meet tangentially, such as fillets; a body number for multi-body files; or a per-triangle "keep sharp normal" flag. Raise the version number.
Widen the face colour to 6 or 7 bits, or the surface type to 4 bits, by taking reserved bits. Use bit 15 only if no colour-convention viewer is a concern.
Flag edges (3 bits per triangle, one per side) instead of corners, to mark sharp or tangent edges.
Identify a face by a run of consecutive triangles in file order plus a run-length code in the attribute words, instead of by colour.

Carrying more than flags

Spread a small parameter record (a plane's normal and offset, a cylinder's axis, point and radius) across the attribute words of consecutive triangles of a face, 16 bits at a time, with the surface type saying how many triangles carry it. The reader must still verify it against the mesh.
Store a compressed STEP, IGES or other CAD file across the attribute words when it fits (section 4.3), with a header key saying so, and fall back to labels when it doesn't. The room is 2 bytes per triangle, so this suits fine meshes of simple parts least, and coarse meshes of complex parts least.
Store a second checksum over the attribute words, or a checksum of the labels only, so a program that edits colours but not geometry can be told apart.

Header

Further key=value fields: part name, source file name, body count, a flag that hardpoints include two-face vertices, a creation date. Readers ignore keys they don't know.
Another checksum (CRC-64, SHA-256 truncated) in place of CRC-32; hash the attribute words too.
A marker after the 80-byte header, such as a first record whose attribute word is the format marker, for programs that rewrite headers.

Writers

Any program that knows the CAD faces and can mesh them: CadQuery, build123d, Onshape, SolidWorks, Blender (from face groups), OpenSCAD (from its own object tree).
A STEP-to-hardpoint-STL command: mesh a STEP file with OpenCASCADE and read the triangulation back face by face. No CAD plug-in needed.
A converter that, after fitting a mesh, writes the labels back into the input's attribute words, copying the triangles byte for byte. (I built this; after converting, the labelled copy converted again to the same result. 12 faces on a bracket, 136 on an organic part.)

Readers

A viewer that colours a file by face or surface type, or checks a file against the format.
A slicer that uses the faces, for example to give round holes different perimeter settings from flat walls.
Tools that strip the labels (hstl.py strip writes a plain STL with identical triangles).

Other carriers (untested)

Per-face groups in OBJ or PLY, or per-triangle properties in 3MF, to carry the same facts. Those formats can hold groups natively; the point of this paper's method is that an unmodified STL carries them.

8.7 The reference implementation

hstl.py (about 600 lines, standard library only): pack_word, unpack_word, make_header, parse_header, geometry_crc, read, decode, colour, encode, write, transfer_faces, describe, verify, strip. Command line: python hstl.py info|verify part.stl, python hstl.py strip part.stl plain.stl.
FreeCAD workbench (HardpointSTL): hardpoint_fc.py (export logic, no GUI code) and hardpoint_stl_fc.py (the command and dialog).
Fusion add-in (HardpointSTL): hardpoint_fusion.py (no adsk imports) and HardpointSTL.py (the command).
Tests, examples and illustration scripts as in section 12.

Appendix A shows a real header and records.

9. What I'd test next (feel free to use this plan)

Slicers. Load bracket_hardpoint.stl and bracket_plain.stl into Cura, PrusaSlicer, OrcaSlicer and Bambu Studio and compare the sliced G-code. If they differ, the format has failed requirement 2 and I want to know.
FreeCAD. Run tests/freecad_selfcheck.py in FreeCAD (0.21, 1.0, 1.1) and send the output. Then export a part you actually modelled.
Fusion. Run Export hardpoint STL and note whether it took the per-face or the whole-body route.
Real models. Export real parts from CAD and compare converter results with and without labels. All my test parts were built for the tests.
Colour-aware viewers. Open a labelled file in a viewer that shows per-triangle STL colours and see whether faces get tinted.
Cone and torus. A converter that builds cone and torus faces from the labels should turn countersinks and rounded edges into one exact face each.
Big meshes. Time the writer on a 500,000-triangle export on a low-end machine, and write a native version only if it is slow.

10. Working together

Nothing here came from one person working alone:

The readers I could study: OrcaSlicer's admesh code, Uranium's STL reader and trimesh are all public, and I could read them. The person who reported OrcaSlicer issue 15993 handed me the reason bit 7 is in the format.
The colour conventions of VisCAM, SolidView and Materialise Magics decided what bit 15 must not be.
The CAD programs' own source and documentation: FreeCAD is open source and its mesher is readable. Autodesk's API pages told me what Fusion would do, and where they stay quiet.
Earlier mesh-to-STEP tools: stlToSolid and breptile showed what is possible without any hints.
What I added: putting these pieces together, building the exporters, measuring the result, and writing down every way it went wrong.

Collaboration in the open does three things a patent never will:

It's faster. One person's dead end saves everyone else the trip. Checking whether a STEP file would fit cost me an afternoon of measuring. With this paper it costs you a table.
It keeps the idea free. A published idea counts as prior art. The more of us write down what we try, with dates and enough detail to rebuild it, the harder it is for anyone to claim what hobbyists worked out together.
It gives better answers. I only tested three parts. More people exporting, converting and comparing results will tell us far more.

An open invitation:

Run the checks in section 9 and post your results, good or bad, as an issue or discussion on the repository. Photos of broken meshes are especially welcome. Failure is data.
Write an exporter for the CAD program you use. hstl.encode takes triangles, a face number per triangle, a type per face and a list of CAD vertices.
Write a reader, or make a converter that uses the labels better than mine does.
Write up your own experiments the same way: dated, public, enough detail to rebuild them. Link back here and I'll link to you.

Everyone who contributes gets credited in the next version.

11. How this was made

My part:

the idea, the six requirements in section 1.2 and the rule that a labelled file must stay a normal STL;
the instruction to research first, and the question about hiding a STEP file;
deciding what to publish, and when.

The AI assistant's part (working to that design):

the research into how readers behave, the format design, the code, the tests, the measurements and the drawings;
the first draft of this write-up;
its share of the mistakes (1 to 6 in section 4.2).

Every measurement in this paper was made by running the code in this repository, or the converter named in section 6, on a Linux cloud machine between 4 and 10 October 2026. None was made on real FreeCAD, Fusion or slicer software.

12. Code, data and how to reproduce

Two repositories:

This paper: a-point-of-contention. Its front page is this paper, generated from paper/paper.md. It also holds the reference reader and writer (code/hstl.py, Python 3, standard library only), the four example files (data/: two parts, each as a hardpoint STL and as a plain STL with the same triangles), the full research notes (notes/DESIGN_NOTES.md) and the specification (notes/HARDPOINT_STL.md).
The program: hardpoint-stl. The FreeCAD workbench and Fusion add-in (plugins/), the installers, the tests (test_hstl.py and test_install.py use the standard library only; test_hardpoint_cad.py needs cadquery-ocp, numpy, trimesh, and optionally numpy-stl; freecad_selfcheck.py runs inside real FreeCAD) and the scripts that regenerate the example files and drawings (tools/make_examples.py, tools/make_illustrations.py).
Not included in either: the converter I measured with. The numbers in section 6 can't be re-run from these repositories. The format checks, round trips and loader checks can.

13. Licence, and keeping it free

Text and figures: Creative Commons Attribution-ShareAlike 4.0. Anyone may copy, share and adapt it. Adapted versions must credit this paper and stay under the same licence.
Code: PolyForm Noncommercial 1.0.0. Free for non-commercial use. It is source-available, not open source.
The methods: dedicated to the public (section 8). A licence on text or code can't stop anyone using a method, and I don't want it to. The point of publishing is that the format stays free for everyone to implement, including commercially, in their own code: from today's date this paper is a dated public description of it.

14. Disclaimers

Untested in the real programs. Nothing here was run in real FreeCAD, Fusion or a slicer. Statements about what those programs do come from their source code or documentation, as cited, and may be wrong.
Measurements. The results in section 6 come from three test parts built for the tests and one converter. They are not a general claim about the format or about anyone else's converter.
Prior art. My search for earlier work was informal (section 2). Nothing here is a statement that the idea is new, or about the validity of anyone's rights, and nothing here is legal advice. Whether and how a defensive publication counts as prior art is a question for a patent attorney.
Other people's work. Product, company and file-format names belong to their owners and are used only to identify them. This project is not affiliated with any of them.
Your files. The exporters write a new file where you choose and don't change your CAD document. A hardpoint STL is meant to be an ordinary STL; if you find one that isn't, please say so before you print it.

15. How to cite

Armstrong, M. (2026). A POINT of contention: STL to STEP conversion shouldn't be that HARD. A proposed hybrid STL format that is CAD-friendly and slicer-compatible. A hobbyist's field notes on the hardpoint STL, including a defensive publication of the format. Version 1.0, 15 October 2026. https://github.com/The-Dorkknight/a-point-of-contention

References

OrcaSlicer, deps_src/admesh/stlinit.cpp (binary or text test, count from file size). https://raw.githubusercontent.com/OrcaSlicer/OrcaSlicer/main/deps_src/admesh/stlinit.cpp
OrcaSlicer issue 15993, small binary STLs imported as empty objects. https://github.com/OrcaSlicer/OrcaSlicer/issues/15993
Ultimaker Uranium, STLReader.py (Cura loads STL through numpy-stl). https://raw.githubusercontent.com/Ultimaker/Uranium/main/plugins/FileHandlers/STLReader/STLReader.py
trimesh, exchange/stl.py (exact-length check, attribute field kept). https://raw.githubusercontent.com/mikedh/trimesh/main/trimesh/exchange/stl.py
STL (file format), Wikipedia: binary layout, the solid rule, the two colour conventions. https://en.wikipedia.org/wiki/STL_(file_format)
FreeCAD source: src/Mod/MeshPart/App/Mesher.cpp, AppMeshPartPy.cpp; src/Mod/Part/App/TopoShape.cpp, BRepMesh.cpp, Tools.cpp; src/Mod/Mesh/App/Mesh.pyi. https://github.com/FreeCAD/FreeCAD
Autodesk Fusion API: TriangleMeshCalculator, TriangleMesh, BRepFace, BRepBody, FileDialog, selection filters.
Autodesk forum, "How can I capture facets from a surface using the API" (per-face meshing example; silent on whether neighbouring faces line up). https://forums.autodesk.com/t5/fusion-api-and-scripts-forum/how-can-i-capture-facets-from-a-surfaces-using-the-api/td-p/7070657
stlToSolid, mesh to STEP by segmentation and primitive fitting. https://github.com/Crypto69/stlToSolid
breptile, mesh to STEP. https://pypi.org/project/breptile/0.1.0/
numpy-stl. https://github.com/WoLpH/numpy-stl · trimesh. https://github.com/mikedh/trimesh · cadquery-ocp (OpenCASCADE 8.0.1). https://github.com/CadQuery/OCP

Pages and source files opened between 3 and 10 October 2026.

Appendix A: a real hardpoint STL

From examples/bracket_hardpoint.stl (59,084 bytes = 84 + 50 × 1,180).

The header, as written (80 bytes, padded with spaces):

HARDPOINT-STL 1 u=mm tol=0.05 ang=15 crc=e67609a0 by=cad-example

The first triangle's 50-byte record, in hexadecimal:

00 00 80 bf  00 00 00 00  00 00 00 00        normal  (-1, 0, 0)
00 00 f0 c1  00 00 80 c1  00 00 20 41        corner 1 (-30, -16, 10)
00 00 f0 c1  00 00 80 41  00 00 00 00        corner 2 (-30,  16,  0)
00 00 f0 c1  00 00 80 c1  00 00 00 00        corner 3 (-30, -16,  0)
80 39                                         attribute word 0x3980

Reading the attribute word 0x3980 = 0011 1001 1000 0000:

Bits	Value	Meaning
0–4	0	face colour 0
7	1	labelled
8–10	1	surface type 1: plane
11–13	7 (all three set)	all three corners are CAD vertices
15	0	as required

python src/hstl.py info examples/bracket_hardpoint.stl prints:

hardpoint STL version 1, 1180 triangles, units mm, written by cad-example
  16 faces (1 cone, 8 cylinder, 7 plane), 25 hardpoints
  meshed to 0.05 mm, 15 degrees

and python src/hstl.py verify examples/bracket_hardpoint.stl ends with RESULT: PASS.

About this repository

Path	What
`paper/paper.md`	The paper (this page is generated from it)
`paper/a-point-of-contention-v1.0.pdf`	The paper as a PDF
`paper/figures/`	Figures
`code/hstl.py`	Reference reader and writer (Python, standard library only)
`data/`	Example files, each as a hardpoint STL and a plain STL with the same triangles
`notes/`	The full research notes, the format specification, and how to archive this paper as prior art
`tools/` · `tests/`	Rebuild the PDF, web page and README; checks
`docs/`	The web version for GitHub Pages

The FreeCAD workbench and Fusion add-in live in the separate
hardpoint-stl repository.

To rebuild: python3 tools/build_paper.py (pandoc and Chromium), then python3 tools/make_readme.py.
GitHub's Cite this repository button uses CITATION.cff.

Join in: run the checks in section 9 and post results with photos as an issue or discussion, write an exporter
for another CAD program, make a converter that uses the labels better, or point out prior art I missed.
Everyone who contributes gets credited in the next version.

Licence: paper text and figures CC BY-SA 4.0; code in code/ and tools/
PolyForm Noncommercial 1.0.0 (source-available, not open source); the methods described are
dedicated to the public as a defensive publication. Not legal advice.

Fin-ally Supported

Matthew Armstrong — Tue, 20 Oct 2026 13:52:44 +0000

Shark-fin supports for long, flat, tilted overhangs: a hobbyist's field guide and a defensive publication

Matthew Armstrong (@The-Dorkknight)\
Version 1.0 · First published 19 October 2026 · Text and figures: CC BY-SA 4.0 · Code: PolyForm Noncommercial 1.0.0\
Repository: https://github.com/The-Dorkknight/fin-ally-supported · Software: https://github.com/The-Dorkknight/cura-shark-support

📄 PDF · 🌐 Web page · 🔧 The plugin · About this repository

This page is the full paper (the same text and figures as the PDF).

Contents: Why this paper exists · The problem · What already exists · Shark fins in one page · The method in detail · How it got here: the mistakes, in order · Numbers · Defensive disclosure: the method and its variations · Test plan (please print this) · Limitations and open questions · Fin-ally, a social species · Code, data and how to reproduce · How this was made · Licence, and keeping it free · Disclaimers · How to cite · References

Read this first. Every number in this paper comes from geometry code, slicer estimates or G-code. Nothing
has been printed and broken yet. Where a result is a slicer estimate or a simulation it says so. Section 8 is a
test plan for anyone with a printer and a free evening.

Abstract

Printing a long box tilted onto one of its long edges makes its walls strong along their length, but turns its base
into a long, flat overhang at 30–55°. That is near, or just past, the angle where slicers start adding support, and over 150 mm it tends to sag and
curl.
Normal slicer supports fix it by filling the space under the whole face with a forest that welds itself to the
part. This paper describes shark-fin supports: a row of thin vertical plates that run downhill under the face,
follow its slope, touch it only at small teeth, stop short of the top with a blunt flat tip, and stand on a crossbar
foot and a one-layer brim pad. They are cheap (on the test box, 1.68 m of filament and about 40 minutes for five
fins, slicer estimate) and should come off in one piece each. The method is implemented as an open Cura plugin with a
toolbar button that lets you click the face you want supported. Section 7 is a defensive disclosure: the method
and a long list of variations are published as prior art, to make it much harder for anyone to patent them and
charge hobbyists for them. They are dedicated to the public.

0. Why this paper exists

To keep it free. A published method is prior art, which makes it much harder for anyone to get a valid patent on it later. This paper puts the shark fin, its teeth, its blunt top, its feet and its many cousins on the public record with a date, so that a company filing on them later has this to get past first.
To write down the dead ends. Every version so far had a mistake in it that looked like a good idea at the time. Section 5 lists them, so nobody has to make them twice.
To bring makers together. A plugin is a tool; a paper is an invitation. Print the test plan, post the results, fork the code, prove me wrong. Everyone who contributes gets credit in the next version.
Selfish reasons. Publishing things like this tends to bring more interesting 3D printing tools and tricks back to me. It also makes me roughly 0.3 % more employable per paper, which, compounded over a few more papers, is a very efficient use of an evening.

1. The problem

1.1 Tilting for strength

FDM parts are weakest between layers. A long box printed flat is strong along its length only in the layers
themselves; printed on its end it is strong in the wrong direction and wobbly. A common compromise is to stand
the box on one long edge and tilt it, so the long walls run along the layers and the base and one side become
sloping faces (Figure 1).

Figure 1. The 35° test box (grey, see-through) and its fins (orange).

The test part used throughout is a 150 × 40 × 25 mm box rotated 35° about one long bottom edge, so its base
becomes a 55° overhang (in Cura's convention: 0° is a vertical wall, 90° a flat ceiling). It is deliberately
boring. Boring parts make honest tests.

1.2 Why "it's under the angle" is not enough

Slicers and rules of thumb treat overhangs up to about 45–55° as printable without support. That is true for a short
ledge. Over a long face several things add up:

each layer's edge sticks out a little further than the one below, and a long free edge cools unevenly and curls upwards, which the nozzle then hits;
the lowest part of the face is printed first and has nothing above it to hold it flat;
a long, thin, freshly printed edge sags under its own weight and the drag of the nozzle.

The usual result is a wavy, curled base, or a print knocked loose halfway through.

1.3 What slicers offer

Turning on normal supports fills the space under the whole base with support. It works, but it uses a lot of
plastic and time, it bonds along every layer of the face, and on a tilted part it leaves a large scarred surface.
Tree supports use less material but branch to many contact points and can be awkward to remove from a long flat
face. Neither knows that this particular overhang only needs a few stiff ribs to stop it curling.

2. What already exists

This section is an informal prior-art search, not a professional one. It is here to give credit and to be clear
about what is new.

Slicer supports. Cura, PrusaSlicer and OrcaSlicer offer grid/line supports, tree or "organic" supports, support blockers and enforcers, painted supports, and "support meshes": any shape the user loads can be marked to print as support (Prusa Knowledge Base; Printago guide).
Hand-drawn sacrificial ribs. Designers have long added thin ribs to a model in CAD to hold up an overhang and snapped them off afterwards (Hubs overview of supports). That is the same idea as a fin, made by hand, usually as a plain plate that bonds along its full edge.
Ribbed support vaults (Tricard, Claux and Lefebvre, Computer Graphics Forum, 2019) grow rib-like internal walls inside hollowed FFF prints to hold up internal overhangs (project page). They are walls that support from below, but inside the object and merging into it.
Teeth on metal supports. In metal powder-bed printing, block supports often meet the part through small teeth, whose size, shape and penetration affect the strength of the support (Materialise). The fins' teeth borrow from that habit.
US 9,469,057 (3D Systems, priority 2012). Claims a method of printing an FFF support whose upper portion contacts the part at discrete "fine points", with a retract, lift, move, lower sequence between them (Justia; Google Patents, which lists it as active until about 2034). Worth knowing: in the top layers of a fin, each tooth tip is a small separate island in the slice, and slicers usually retract and travel (and may lift) between islands. How this patent relates to Shark Support has not been assessed. If it matters to you, ask a patent professional; nothing here is legal advice.

As far as this search found, nobody describes downhill fins generated automatically under a flat tilted face,
contacting through teeth, cut short with a blunt top, braced by a crossbar foot and brim pad, with a click-to-pick
face selection. If you know of earlier work, please open an issue: the next version will credit it.

3. Shark fins in one page

For each flat face that faces downwards:

Downhill. Work out the direction a ball would roll down the face, flattened onto the bed. Fins run that way, spaced evenly across the face (30 mm by default, 4 mm in from the sides). Figure 2.
Measure. Along each fin line, cast vertical rays up from the bed every 0.5 mm to find the part's underside.
Shape each fin as a thin vertical plate (2.4 mm thick at the bed, 1.2 mm at the top) whose top edge sits 1 mm under the part, with teeth every 3 mm that reach up to 0.15 mm short of it. The first two teeth from the low end reach 0.1 mm into the part, so the start of the overhang, where curling begins, is anchored.
Stop early. The fin follows the part only to 85 % of its height; the part bridges the rest. The fin ends in a 5 mm flat top, then goes straight down.
Stand it up with a 4 mm high crossbar foot under the tip and a 4 mm wide, one-layer brim pad.
Print it as a solid little part next to the model, not as Cura "support".

Figure 10. One fin of the test box, side view, drawn from the code's output and labelled.

4. The method in detail

This section is written so that someone could rebuild the method from it.

4.1 Finding the face

Automatic mode. Triangles of the model that face downwards are grouped into flat faces: two triangles join when
they share an edge and their normals differ by less than 3°. A face qualifies when its overhang angle α (the angle
between its outward normal and the horizontal, so 0° is a wall and 90° a ceiling) lies between 20° and 70°, its area
is at least 300 mm², and it spans at least 15 mm downhill, measured in plan.

Picked mode. The user clicks the face. The slicer reports the 3D point under the mouse (in Cura, its picking
render pass). The plugin finds the triangle that contains the point (the projection of the point lies inside the
triangle within a small tolerance, and the point is within 1 mm, or 1 % of the model size, of its plane), checks
that it faces downwards and is not a flat ceiling, and uses the flat face that triangle belongs to. A picked face
ignores the automatic angle and size limits: the user has said it needs help.

4.2 Direction and layout

For a face with unit normal n, gravity g = (0, 0, −1) projected into the face's plane is
d = g − (g·n)n, the steepest descent. Its horizontal part, normalised, is the downhill direction
h; c = ẑ × h is across. Projecting the face's corners onto c gives its width; fins sit at
evenly spaced positions across it, a side margin from each edge, at most a set spacing apart (one fin in the middle
if the face is narrow). A flat ceiling has no downhill and is skipped.

4.3 Measuring the underside

Along each fin line, at steps of 0.5 mm in h, a vertical ray goes up from the bed. For a closed mesh the first
surface a ray meets from below always faces downwards, so only downward triangles are indexed, in a uniform grid in
plan. Each hit gives the height of the part above the bed and which triangle was hit. The fin keeps the longest
continuous run of samples that hit its own face and are at least the start height (4 mm) above the bed, so it
never climbs onto a neighbouring face or across a gap. Below the start height the face is short enough to print on
its own.

4.4 The top edge: relief, teeth and anchors

Let s run along the fin from its low end s₀, and z(s) be the underside height. The fin's top edge is
z(s) − relief (1 mm). Teeth are placed from the low end: the first tooth's ramp starts at s₀, then one every
pitch (3 mm), and a last one near the end. Each tooth ramps up over 1 mm, stays flat for 0.6 mm, and ramps down.
At its flat top it reaches z(s) − gap (0.15 mm) or, for the first N anchor teeth (2), z(s) + overlap
(0.1 mm, half of a 0.2 mm layer). The anchors therefore print touching the part's outer wall in the same layers
(Figure 6); the other tips stop just short.

Why teeth and not a plain edge: a plain edge 0.15 mm under a sloping face touches it along every layer. Teeth turn
that into a dotted line, so the fin snaps off with a short pull and leaves small, evenly spaced marks.

4.5 Stopping short, with a blunt top

The fin follows the part only up to a height z_cut = (1 − top cut) × the highest edge height it would otherwise
reach (top cut 15 %, so 85 %). Teeth near the cut are flattened to z_cut so nothing pokes above it. From there the
fin runs flat for 5 mm (tip length), then ends.

Why: a sharp tip means the last layers of the fin are a few millimetres long or less. The printer brakes and
accelerates for each tiny move, which is slow and prints badly. With a 5 mm flat top, no layer of the fin is shorter
than 5 mm. And the top 15 % of a long tilted face is the part closest to its own upper edge, which is already held
by the rest of the box.

4.6 The back edge

By default the fin goes straight down from the end of the flat top. Variants (Figure 9) lean the back out at a
set angle (20° from vertical) for a wider base, or make it round (a quarter ellipse) or concave. Each point of the
back is checked against the part above it and lowered if needed, and the back never goes below a 0.6 mm stub.

4.7 Thickness

The fin is a "ribbon" of columns along s. Each column has a bottom width (2.4 mm), a top width that tapers linearly
with height from 2.4 to 1.2 mm, and a top height. Neighbouring columns are joined into a closed, outward-facing
mesh. Thicker at the bed, where bending is worst; thin at the top, where the teeth are.

4.8 Crossbar foot

A bar across the fin, 2 mm thick and 4 mm high, its length ¼ of the fin's footprint (at least 10 mm), under the
middle of the flat top, where the fin is tallest. Fins with a footprint over 100 mm get a second bar halfway
between the low end and the 85 % cut.
A bar is lowered if the part comes within the relief above it, and skipped if that leaves less than 1.5 mm.

4.9 Brim pad

A rectangle one first layer thick, 4 mm wider than the fin on every side, plus one around each crossbar. Where the
part itself comes close to the bed at the low end, the pad is trimmed until the part is at least 1 mm above it, so
it never welds to the part's own edge.

4.10 Solid part, not "support"

Cura can print any mesh as support, but its support settings are global: density, walls and pattern cannot be set
per object, so a 1.2 mm fin printed as support would come out as a few sparse lines. And in the Cura releases
checked, the setting called "support brim" prints a brim inside support areas, not around them. So by default the
fins are a separate ordinary object with three per-object settings: infill 100 %, support off, and "union
overlapping volumes" on, so a fin, its crossbar and its pad print as one piece. The gaps between fin and part are
in the geometry itself. A "print as support mesh" switch is kept for comparison.

4.11 In the slicer

In Cura the method is a toolbar button under move, scale and rotate (Figure 7). Its panel has Pick face,
Auto, Remove all and Settings. Picking a face that already has fins replaces them; Auto replaces a model's
earlier fins. All of it is undoable. For other slicers a command line tool writes the fins as an STL to load next to
the part.

Figure 7. Cura (from source) with the Shark Support panel open: a mouse click on the underside, sent by the test
driver (xdotool, virtual display), made these fins.

Figure 8. The same box after Auto, from behind: five fins with their feet and pads.

4.12 All the numbers

Parameter	Default	Meaning
Overhang angle range (auto)	20–70°	Which faces Auto supports
Smallest face, shortest slope (auto)	300 mm², 15 mm	Faces smaller than this are left alone
Fin spacing, side margin	30 mm, 4 mm	Across the face
Start height	4 mm	Fins start where the face is this high
Thickness at bed / top	2.4 / 1.2 mm	Linear taper with height
Relief	1 mm	Gap under the part between teeth
Tooth pitch, tip, ramp	3, 0.6, 1 mm	Tooth shape
Tip gap	0.15 mm	Ordinary teeth stop this far under the part
Anchor teeth, overlap	2, 0.1 mm	First teeth from the low end reach into the part
Top cut	15 %	Fin stops at 85 % of its height
Tip length	5 mm	Flat blunt top
Back	vertical	Or leaning (20°), round, concave
Crossbar	¼ of footprint × 4 mm high × 2 mm	Under the tip; second one over 100 mm
Brim pad	4 mm wide, one first layer	Around fin and crossbar
Ray step	0.5 mm	Profile resolution

5. How it got here: the mistakes, in order

Most of the versions below were built, tested in code and looked at; two were design dead ends caught before the
first release. Each taught something.

Figure 3 is drawn with today's code and each version's settings, so tooth positions follow today's rule.

0.1.0: the actual shark. A round back edge, because it looked like a fin and seemed sturdier. It was neither: the crossbar already stops the fin tipping over, and the round back was a strip of plastic sticking out past the part. Measured later: 2.27 m of filament against 1.74 m without it (Figure 4).
0.1.0: teeth centred along the fin. The row of teeth was centred, so the first contact could sit up to 15 % of the way in, leaving the start of the overhang, where curling begins, unheld. Fixed in 0.1.1 by starting at the low end.
Before 0.1.0 (design): "support brim" is not a brim. The plan was to use Cura's support brim for the 4 mm pad. Reading Cura's settings showed it prints inside support, not around it. The pad became geometry.
Before 0.1.0 (design): fins as Cura support. Printed at the global support density, a fin is a few lines. Fins became solid objects (section 4.10).
0.1.1: the triangle. Straight back: 23 % less filament (27 % less fin volume). Still a sharp tip.
0.1.2: more teeth, two anchors. Pitch halved from 6 to 3 mm. The first two teeth reach 0.1 mm into the part; the rest stop 0.15 mm short (was 0.2). Almost free: 1.76 m instead of 1.74 m. With 3 mm pitch the valleys between teeth are only 0.4 mm long, so the top edge is effectively a saw blade. If it grips too hard, 4 mm pitch opens the valleys again.
0.2.0: the blunt top. Looking at a Cura preview made the problem obvious: the tip of a triangle is a column of tiny, slow layers. Cutting at 85 % with a 5 mm flat top fixed it and saved time: 1.68 m, about 40 minutes.
0.2.0: the leaning back, measured and demoted. The first sketch of the new shape had the back leaning out to the bed. Measured, it cost more than going straight down (1.97 m, about 42 minutes). It is now an option for when a wider base matters more than plastic.
Plugin plumbing, for other plugin authors:
- Uranium's signals hold weak references, so connecting a lambda silently does nothing. Connect a method.
- Cura caches "is this a support mesh" per object and only refreshes it when a setting change is announced; setting it directly leaves the cache stale.
- A plugin's first log lines can appear before Cura's log file is open; log again once the app has started.
- UM.Dialog takes only visual items as children: a Connections object in the wrong place makes the whole dialog fail to load.
- Toolbar icons are SVGs that Cura recolours by inserting a fill attribute into the <svg> tag. An icon that already has one there becomes invalid.

6. Numbers

All from PrusaSlicer 2.7.2's command line on the fins alone: 0.2 mm layers, 0.4 mm nozzle, two perimeters,
PrusaSlicer's default speeds. These are slicer estimates, not stopwatch times.

Version	Fins (5)	Filament	Time (estimate)	Volume (code)
0.1.0 round back	sharp, to the top	2.27 m	48 min	4.7 cm³
0.1.1 triangle	sharp, to the top	1.74 m	42 min	3.4 cm³
0.1.2 more teeth	sharp, to the top	1.76 m	43 min	3.5 cm³
0.2.0, leaning back	blunt, 85 %	1.97 m	42 min	4.0 cm³
0.2.0 default	blunt, 85 %	1.68 m	40 min	3.3 cm³

Volumes are without brim pads and crossbars; filament and time include them. The 0.1.0 and 0.1.1 volumes are
redrawn with today's code, so their tooth positions follow today's rule.

Does the slicer print what the code drew? Figure 5 plots every extrusion in the real G-code within 0.5 mm of the
middle fin. The fin is solid, follows the part with a stepped gap, stops below the top of the face with a flat top,
and goes straight down at the back. Figure 6 zooms in on the low end: the anchor teeth's lines run into the part's
outer wall, while further up there is a clear gap at every tooth.

Figure 5. Every extrusion in the PrusaSlicer 2.7.2 G-code within 0.5 mm of the middle fin, seen from the side.

Figure 6. The low end of the same fin, zoomed in.

Speed of the code. A 196,608-triangle version of the test box took about 2 s to process (1.6–2.3 s across
runs) on the development machine; the 12-triangle box takes 0.02 s. Not yet timed on a 7th-generation Core i3, which is the target for
everything in this project.

A box on its corner. Rolled a further 12° onto a corner, both faces next to the standing edge qualify, and the
same code makes ten fins; with the anchors switched off, the closest tooth is exactly 0.15 mm under the part
(Figure 11).

Figure 11. The box rolled 12° onto a corner: two faces, ten fins.

7. Defensive disclosure: the method and its variations

The following are disclosed as part of this publication, alone and in any combination, for FDM/FFF and for any
other layer-wise process where they make sense. They are dedicated to the public.

7.1 The core. A support structure for a downward-facing surface of an object being built layer by layer,
comprising one or more upright plates ("fins") generated from the object's geometry, each running substantially
along the downhill direction of the surface in plan, whose upper edge follows the surface at a clearance, with
contact features ("teeth") that approach or meet the surface at intervals, the plates standing on the build
surface, optionally braced by a foot and widened at the base by a pad.

7.2 Finding where fins go. Automatic detection of flat or near-flat downward faces by angle band, area and
reach; grouping by normal tolerance; user selection by clicking a point on the surface, by painting, by drawing a
line or region, or by selecting a face in CAD; selection of faces by curl risk (length of free edge, cooling time,
distance from the bed, material); faces of any size, including faces normally considered printable; curved or
faceted surfaces approximated piecewise; surfaces of multiple objects at once.

7.3 Layout. Fins along the downhill direction; at an angle to it; fanned from a point; in a grid or herringbone;
crossing pairs (X); spacing fixed, scaled with overhang length, with angle, with face width, with material, or set
so that the unsupported span between fins stays below a limit; denser near the low edge where curling starts;
offset between neighbouring faces; joined across faces into one structure.

7.4 Contact. Teeth of any profile (trapezoid, triangle, rounded, stepped); points, ridges, pins, cones, fingers;
teeth whose pitch varies along the fin (denser at the low end); anchor teeth that touch or overlap the part,
anywhere along the fin and in any number, with any overlap; teeth that stop short at a gap of any size, fixed or
proportional to the layer height; teeth printed with a different material, extruder, temperature, speed, flow or
cooling; teeth with a breakaway neck or perforation; teeth that touch only in alternate layers; an interface layer,
dissolvable or not, between teeth and part; contact made from the side rather than from below.

7.5 Profile. A top edge that follows the surface at a relief; fins that stop at any fraction of the surface's
height (the part bridging the rest), measured by height, by length along the slope or by the angle of the
remaining span; a blunt top of any length or a minimum layer length, so that no layer of the support is shorter
than a set length; a flat, rounded or stepped top; backs that are vertical, leaning at any angle, round, concave,
stepped, or shaped to the minimum stable footprint; fins that start at a set height or reach down to the bed edge.

7.6 Section and structure. Thickness constant, tapered, stepped or thickened at the base; solid, hollow,
double-walled, corrugated, perforated, lattice-filled or sparse-infilled fins; fins with stiffening ribs or a
flange along the top; fins printed as part of the model, as a separate object, as a slicer "support mesh", or
directly as toolpaths at G-code level.

7.7 Feet and pads. A crossbar of any length, height and position (under the tip, at the middle, at the low end,
several); T, X, H or gusset-shaped feet; triangular gussets between fin and bed; a pad of any width and thickness,
one or more layers, trimmed clear of the part, shared between neighbouring fins, or replaced by a raft or by mouse
ears; tie bars linking fins to each other above the bed.

7.8 Workflow. Generating fins in a slicer, a CAD program, a mesh editor, a plugin, a command line tool or a
web service; replacing earlier fins when the same face is picked again; regenerating fins when the object is moved;
removing all fins at once; previewing before adding; combining fins with tree or normal supports elsewhere on the
same part; automatically turning off the slicer's own supports under the faces that have fins.

8. Test plan (please print this)

Print the 35° test box (data/tilted_box_35deg.stl, 150 × 40 × 25 mm) four ways, same filament, same settings:

No support. Photograph the base, measure curl at the low edge and mid-face with a feeler gauge or a ruler on a flat surface.
Slicer supports (normal, then tree), touching build plate only.
Shark fins, defaults.
Shark fins, anchors off (Anchor teeth 0).

For each, record: filament and time (slicer estimate and real), whether it finished, curl or sag of the base,
time to remove the supports by hand, and the state of the base afterwards (photo). Then, if you are keen: tooth pitch
3 vs 4 vs 6 mm; top cut 0, 15 and 25 %; a 45° box. Post your results as a GitHub issue or discussion with photos.
Everyone who does gets credited in version 1.1.

10. Fin-ally, a social species

Infant sharks do, do, do support prints well.

(With apologies to a certain children's song, which is now going to be in your head until at least Thursday.)

The serious point behind the joke: this method grew one review at a time. A fin that looked right in a diagram
looked wrong in a slicer preview; a "more efficient" back edge turned out to cost more when measured. Each change
came from someone looking at the output and saying "that bit's daft". The fastest way to find the next daft bit is
more people looking. Print it, break it, measure it, and tell the rest of us. Makers, like fins, are stronger when
they are spaced sensibly and braced against each other.

11. Code, data and how to reproduce

The plugin (Cura toolbar tool, menu, installer, command line tool, 22 geometry tests): https://github.com/The-Dorkknight/cura-shark-support, version 0.2.1-wip (fin shapes as in 0.2.0).
In this repository: code/shark_core.py (the geometry, numpy only), data/ (the test boxes and their fins as STL), tools/make_figures.py (redraws Figures 1–4 and 9–11 from the code), tools/gcode_side_view.py (draws Figures 5–6 from any G-code), tools/build_paper.py (builds the web page and PDF).
Figures 5 and 6: PrusaSlicer 2.7.2, --layer-height 0.2 --first-layer-height 0.2 --nozzle-diameter 0.4 --perimeters 2 --fill-density 15%, the box and its fins merged. Figures 7 and 8: Cura from source, run by the plugin's own test driver under a virtual display.

12. How this was made

The geometry code, plugin, tests, measurements and literature search were done with an AI assistant (Claude,
by Anthropic) working to my design intent, reviewed and steered by me at each step: the shark fin, the point
contacts, the 4 mm brim, the crossbar, the triangle, the anchors, the blunt top and the toolbar button were all my
calls; the assistant did the typing, the maths and the measuring, and owned up to its own mistakes listed in
section 5. I think saying so plainly makes the work more trustworthy, not less.

13. Licence, and keeping it free

Text and figures: CC BY-SA 4.0. Share and adapt, credit me, keep it under the same licence.
Code: PolyForm Noncommercial 1.0.0 (LICENSE-CODE.md). Free for hobbyists; commercial use needs permission.
The methods in sections 3, 4 and 7 are dedicated to the public. This paper is a defensive publication: its purpose is to be prior art, to make it much harder for anyone to patent these methods and restrict their use.

14. Disclaimers

Not legal advice: what counts as prior art, and whether something infringes a patent, is decided by patent offices
and courts. Not engineering certification: printed supports can fail, and parts can detach from the bed. Use at
your own risk. Not affiliated with UltiMaker, Prusa Research, 3D Systems, Materialise or anyone else named here.

15. How to cite

Armstrong, M. (2026). Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs. A hobbyist's field
guide and a defensive publication. Version 1.0, first published 19 October 2026.
https://github.com/The-Dorkknight/fin-ally-supported

References

Prusa Research, "Support material", Prusa Knowledge Base. https://help.prusa3d.com/en/article/support-material_1698/
Printago, "How to Add Supports in PrusaSlicer (Including Organic and Custom)". https://printago.io/guides/prusaslicer-supports
Hubs, "Supports in 3D printing: a technology overview". https://www.hubs.com/knowledge-base/supports-3d-printing-technology-overview
T. Tricard, F. Claux, S. Lefebvre, "Ribbed Support Vaults for 3D Printing of Hollowed Objects", Computer Graphics Forum, 2019. https://www.unilim.fr/pages_perso/frederic.claux/blog/2019/2019-06-21_Ribbed_support_vaults.html
Materialise, "How to create optimal support structures for metal 3D printing". https://www.materialise.com/en/inspiration/articles/optimal-metal-supports
3D Systems, Inc., US 9,469,057 B2, "Support structures and deposition techniques for 3D printing", filed 17 May 2013, issued 18 October 2016. https://patents.justia.com/patent/9469057
Google Patents entry for US9469057B2 (status as listed on 19 October 2026). https://patents.google.com/patent/US9469057B2/en
Software: The-Dorkknight/cura-shark-support, version 0.2.1-wip. https://github.com/The-Dorkknight/cura-shark-support

About this repository

Path	What
`paper/paper.md`	The paper (this page is generated from it)
`paper/fin-ally-supported-v1.0.pdf`	The paper as a PDF
`paper/figures/`	All figures
`code/shark_core.py`	The fin geometry (Python, numpy only), as used by the plugin 0.2.0 and 0.2.1-wip
`data/`	The test boxes and their fins as STL
`tools/`	Redraw the figures (`make_figures.py`), plot G-code (`gcode_side_view.py`), build the PDF and web page (`build_paper.py`), write this page (`make_readme.py`)
`docs/`	The web version for GitHub Pages

To rebuild everything: python3 tools/make_figures.py (numpy, matplotlib, Pillow), then
python3 tools/build_paper.py (pandoc, Chromium), then python3 tools/make_readme.py.

GitHub's Cite this repository button uses CITATION.cff.

Join in: print the test plan (section 8), post results with photos as an issue or discussion, fork it, port it to
another slicer, or point out prior art I missed. Everyone who contributes gets credited in the next version.

Shark Support for UltiMaker Cura

Matthew Armstrong — Tue, 20 Oct 2026 13:42:30 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN (proof of concept, 0.2.1-wip)

Source-available · Non-commercial. Copyright Matthew Armstrong. Licensed under the
PolyForm Noncommercial License 1.0.0. No warranty, no liability: use at your own risk.

Shark Support adds thin shark-fin supports under big, flat, tilted faces. The typical case: you print a long
box tilted onto one long edge so it is strong along its length. Its base becomes a long 30–55° overhang that is
fine in theory but sags or curls over that length. Shark Support puts a row of fins under it:

each fin is a thin vertical plate that follows the slope of the part, stops at 85 % of its height (the part bridges the last bit), has a blunt 5 mm flat top (no tiny, slow top layers) and a straight back down to the bed
it only touches the part at small teeth, a dotted line of points every 3 mm that snaps off cleanly, starting right at the fin's low end. The first two teeth really touch (0.1 mm into the part) to hold the start of the overhang; the rest stop 0.15 mm short
a crossbar foot under the tip (¼ of the fin's length, 4 mm high) and a 4 mm one-layer brim pad keep tall fins standing
in Cura it is a button in the left toolbar: pick the face you want supported with the mouse, or press Auto for every big tilted flat face, and Remove all to clear them

Real screenshot: the plugin running inside Cura (5.15 development source, see Testing), with
fins under the 35° test box and the Shark Support panel open from its toolbar button.

Use it

Load your model and tilt it the way you will print it (Rotate tool, Lay flat, etc.).
Select it, then click the shark-fin button at the bottom of the left toolbar (under move, scale, rotate, mirror, per-model settings and support blocker). Its panel opens:

Pick face, then click the underside face that needs support. Fins appear under that one face. Pick more faces the same way; picking a face again replaces its fins (handy after changing settings). Press the button again to stop picking. Turn the view so you can see the underside (a low side view works).
Auto: fins under every big tilted flat face of the selected model(s), replacing their earlier fins.
Remove all: removes every Shark fin object.
Settings...: the numbers below.
1. A message says how many fins were made. New objects called Shark fins (your model...) appear.
2. Slice and print as usual. Normal support for that model is switched off (a per-model setting) so Cura does not add its own supports under the same face. You can change that in the settings.

The same actions are in the menu Extensions > Shark Support. If you move or rotate the model afterwards, use
Remove all and add the fins again: they are a separate object and do not follow the model.

Settings (Settings... in the panel, or Extensions > Shark Support > Settings...)

Setting	Default	What it does
Overhang angle from / to	20° / 70°	Auto puts fins under faces in this range (Cura's angles: 0° = wall, 90° = ceiling). A face you pick gets fins whatever its angle, as long as it faces down
Smallest face / Shortest slope	300 mm² / 15 mm	Auto leaves smaller faces alone (picked faces ignore this)
Fin spacing / Side margin	30 mm / 4 mm	Distance between fins across the face, and from its sides
Start height	4 mm	Fins start where the face is this high (low down it needs no help)
Thickness at bed / at top	2.4 / 1.2 mm	Fins taper; with a 0.4 mm nozzle that is 6 lines at the bed, 3 at the top
Gap between teeth	1 mm	The fin edge stays this far under the part except at the teeth
Tooth spacing / tip length	3 / 0.6 mm	The contact points. The first tooth starts at the fin's low end, the last sits at the tall end
Tip gap	0.15 mm	All teeth except the anchors stop this far under the part. Smaller = stronger contact, harder removal
Anchor teeth / overlap	2 / 0.1 mm	The first teeth from the low end reach this far into the part so they bond slightly and hold the start of the overhang. 0 turns it off
Top left free	15 %	The fin stops this far below the top of the face; the part bridges the rest. 0 runs it to the top
Blunt tip length	5 mm	The fin's flat top. No layer of the fin is shorter than this, so the printer never slows down for tiny top moves
Back lean	20°	Only with Lean the back out on
Crossbar length / height	0.25 × fin / 4 mm	The foot across the fin under its tip (a second one in the middle for fins over 100 mm)
Brim width / thickness	4 mm / first layer	One-layer pad around each fin and crossbar
Lean the back out to the bed	off	The back slopes out 20° instead of going straight down: wider base, but more plastic and time (test box: 1.97 m and 42 min instead of 1.68 m and 40 min). The command line also offers round and concave backs
Print fins as a Cura support mesh	off	Experimental: Cura then prints them with your support pattern and density

Extensions > Shark Support > Run self-check builds a test box in memory, runs the plugin's own code against it
(including face picking and the toolbar button),
and shows PASS/FAIL per check (also saved to shark_support_selfcheck.txt in your temp folder). Run it once after
installing.

Without Cura (PrusaSlicer, OrcaSlicer, anything)

The geometry code needs only numpy, so there is a command line tool:

python3 shark_cli.py part.stl                   # writes part_fins.stl
python3 shark_cli.py part.stl --spacing 25 --merged part_with_fins.stl
python3 shark_cli.py part.stl --back slope       # back leaning out instead of straight down
python3 shark_cli.py --help                     # every setting

The STL must already be oriented for printing (Z up, sitting on the bed). Import the fins STL as a second part at
the same position (PrusaSlicer: Add part; or slice the --merged file). The repository has examples in
examples/.

Real G-code: the merged test box sliced by PrusaSlicer 2.7.2 on the command line, showing every extrusion within
0.5 mm of the middle fin. The fin is solid, touches the part only at the teeth, stops below the top of the face
with a flat top, and goes straight down at the back.

What exists and what does not

Exists (0.2.1-wip)	Does not exist yet
Fins under flat tilted faces: picked with the mouse, or found automatically	Fins under curved or organic surfaces (it needs flat faces)
Fins cut at 85 %, blunt flat top, straight back, teeth every 3 mm, 2 anchor teeth, crossbar, brim pad	Painting exactly where on a face fins go
Cura toolbar button with panel, menu, settings dialog, self-check, undo	Fins that follow the model when it is moved
Installer that checks Cura's log; `.curapackage`	Live preview while editing settings
Command line tool for any slicer	PrusaSlicer / OrcaSlicer plugin (they have no Python plugin API)
Experimental "Cura support mesh" mode	A real print test (see below)

What was tested

Be aware of exactly what has and has not been tried:

Geometry: 22 automatic tests (python3 tests/test_core.py): closed outward meshes, fins never reach into the part (only the anchor teeth reach in, exactly 0.1 mm; with anchors off every tip is 0.15 mm below it), boxes tilted 35° and 45°, turned on the bed, standing on a corner, the 85 % cut and 5 mm flat top, picking a face (and refusing a top face or a miss), triangle-soup input, spacing, long fins, no fins on a plain cube. A 196,000-triangle mesh took about 2 s on the development machine (not timed on a 7th-gen Core i3).
Inside Cura: Cura could not be downloaded in the build sandbox, so it was run from Cura's and Uranium's source (5.15 development branch, plugin SDK 8.13) under a virtual display, with stand-ins only for Cura's C++ parts. There the plugin loaded, its toolbar button appeared and opened its panel, a real mouse click (sent with xdotool) on the box's underside made fins for that face, picking it again replaced them, Auto replaced those with automatic fins with the right per-object settings, the menu and dialog opened, the self-check passed, support-mesh mode and Remove all fins worked, and Cura's package manager listed it as installed, both after the installer and after Cura's own .curapackage route. Slicing in Cura was not tested (the slicing engine is one of the C++ parts that could not run).
Slicing: the fins were sliced for real with PrusaSlicer 2.7.2 (command line), picture above. For the test box the fins take 1.68 m of filament and about 40 minutes on their own (PrusaSlicer defaults, 0.2 mm layers); the 0.1.2 fins, which ran to the top with a sharp tip, took 1.74 m and about 43 minutes. The zoom below shows the anchor teeth meeting the part's outer wall in the G-code while the other teeth leave a gap.

Not tested: a real print, Cura 5.0–5.10 releases (face picking uses a different path there, written to match Cura 5.0's own support blocker but not run), Windows and Mac (launchers and installer), Flatpak Cura.

Research paper

Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs (version 1.0, first
published 19 October 2026) · PDF

Everything behind this plugin written up: the problem, what already exists (including a live patent on "fine point"
supports and how this differs), the method in enough detail to rebuild it, every mistake made on the way, the
numbers, a test plan, and a defensive disclosure of the method and its variations, dedicated to the public so
nobody can patent them. It is published on its own at
The-Dorkknight/fin-ally-supported; paper/ is a copy that
travels with the plugin. Text and figures: CC BY-SA 4.0. Infant sharks do, do, do support prints well.

How to cite: Armstrong, M. (2026). Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs. A
hobbyist's field guide and a defensive publication. Version 1.0, 19 October 2026.
https://github.com/The-Dorkknight/fin-ally-supported

HOW_IT_WORKS.md: what the plugin reads, changes and never touches
DESIGN_NOTES.md: research notes, decisions, measurements, ideas
paper/: the research paper (Markdown and PDF)
CHANGELOG.md · CONTRIBUTING.md · SECURITY.md · THIRD_PARTY.md

Not affiliated with or endorsed by UltiMaker. "Cura" and "UltiMaker" are names of their owners.

Source code: The-Dorkknight/cura-shark-support on GitHub

FREE (open) Lizard Scanner

Matthew Armstrong — Mon, 19 Oct 2026 20:45:24 +0000

Paused for a month or two. Calibration turned out to be more boring than cleaning, and after weeks of
mad science projects the cleaning has been neglected for long enough. The app works as far as described
below; the notes say exactly where it stopped. Issues and ideas are still welcome.

The paper: Down the Lizard Hole, the whole reverse-engineering
story in plain English (also in its own repository,
down-the-lizard-hole).

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN. Version 0.5.2-wip. Proof of concept.
The camera control, the light buttons and the diagnostics have run on the owner's real CR-Scan
Lizard. The first real wall test (0.4) failed because the projector throws stripes, not dots;
0.5 rebuilds depth for the stripes and was checked on that wall test's saved data and one saved
picture (walls back within 2 mm). The first live test (19 October) gave a flat wall where the
calibration was good, with wrong-stripe streaks that 0.5.1 removes; a second calibration did worse for
reasons not yet known. See the findings.

Licence: PolyForm Noncommercial 1.0.0. Source-available, non-commercial.
Free for personal and other non-commercial use; commercial use needs permission. No warranty
and no liability: it is provided as is. Not made by, or affiliated with, Creality.

A standalone app for the Creality CR-Scan Lizard 3D scanner that does not need Creality's
software: a live infrared picture, automagic buttons instead of sliders for the light, a
wall test that gives the scanner a rough depth calibration, a live depth view, point-cloud
export and recordings. It is built on the bones of
Scantastic and the Lizard engine from
Who are yoUSB?, and is laid out so the Lizard
can move into Scantastic later (INTEGRATION.md).

Screenshots are of the built-in simulated scanner, not a real Lizard.

What exists, and what does not

Works (on the simulated scanner)	Not yet
Finding the Lizard's two cameras (USB bcdc:000a / 000b) and starting them (Linux)	Tried on a real Lizard with this app
Live picture, "pattern only" view, camera A + B side by side	Full 3D scans (many views joined into a mesh): that is Scantastic's job, see INTEGRATION.md
AUTO-TUNE, three presets, Brighter / Dimmer, flash capped at 1 ms	Lens distortion correction
Diagnostics: 10 checks and a report zip
Wall test: rough depth calibration from 3 to 5 walls, saved as you go, all in one folder, one-click zip	Creality's own factory calibration (not found)
Live depth view, save points as .ply	Windows and macOS camera paths (written, never run)
Recording sessions and playing them back	Colour (the Lizard's pictures are infrared)
Light test, "What is camera B?" test

Using it

1. The picture

Plug the Lizard in. On Linux the picture starts by itself within a few seconds (the app
looks for it every 2.5 s). The green tag on the picture says how many pictures a second
arrive and how much of the view shows the projector's stripes. The projector (camera A's light)
flashes once per picture, so every picture carries its pattern; the red glow looks like flicker.

The View row switches between:

Picture: the infrared picture with the projector's stripes.
Pattern only: the stripes with the background light taken away. What the depth is made from.
Depth: needs a wall test first.
A + B: both cameras side by side.

2. The light: automagic buttons

Creality's own app only ever changes two settings, exposure and gain. Here they are a
ladder of 11 light levels instead of two sliders:

AUTO-TUNE walks the ladder until the stripes are bright but not blown out, from whatever is in front of the scanner. Press it again to stop.
Shiny / white, Normal, Dark / black: presets. Normal is what Creality's app uses (1 ms, gain 65); Shiny / white is its dimmest setting.
Dimmer / Brighter: one step of the ladder.

The ring's brightness is the flash length. The white ring is camera B's light, the infrared
projector camera A's. Both cameras start at Creality's 1 ms, never on their own automatic exposure,
and camera B follows these buttons whenever it runs. The ring and the projector flash for as
long as the camera exposes, and at Creality's 1 ms the ring is already very bright. So the
ladder never flashes longer than 1 ms; above that it adds gain (picture amplification), which
brightens the picture without touching the lights. The bar under the buttons shows the rungs.

Allow longer flashes: an advanced switch, with a warning, for dark objects. Brighter then goes up to 6 ms (the camera's own starting value, never more); those rungs show red. It switches itself off when the app closes.
Camera's own settings (long flashes): back to the camera's own automatic exposure. Only with longer flashes allowed, because the camera then picks its own (often long) flash.

Every raw setting is still there under Every camera setting (advanced); setting a flash longer
than 1 ms there asks first.

3. The wall test: rough depth calibration

The Lizard's camera A sees a fixed pattern from its projector: dense vertical stripes, each a string
of beads whose width wobbles. When the scanner moves closer to a wall, the stripes slide sideways in
the picture, by an amount that depends on the distance (and, on the real scanner, a little on where
in the picture). The beads' wobble tells one stripe from the next. Measure that slide at a few known
distances and every picture afterwards can be turned into depth. The original Kinect worked the same
way with dots.

You need a flat, plain, matt wall and a tape measure. About five minutes.

Press WALL TEST.
Point the scanner straight at the wall. Measure to the wall from one fixed point on the scanner (the front glass is easiest; any point works if you use the same one every time; depth is then counted from that point) and type the distance in millimetres.
Press RECORD THIS WALL and hold still for two seconds. (Before the first wall the app runs AUTO-TUNE by itself.)
Repeat at five distances: 18, 23, 28, 33 and 38 cm are suggested (Creality gives the Lizard's working range as 15 to 40 cm). Three is the least; spreading the walls over the whole range matters, because depth gets less certain beyond the nearest and farthest wall.
Nothing to press to save. Every wall is saved the moment it is recorded, and from the third wall on the calibration is fitted and saved by itself; the Depth view turns on. The list shows how well each wall fits, and the window warns about a wall at an angle (one that disagrees with the others is left out) or a scanner turned to the wall. FIT AND SAVE AGAIN is only needed after typing a picture width.

Everything for one scanner's calibration is in one folder, calibration/<serial>/: the fit
(calibration.json), the wall patterns and K map (reference.npz), the measured shift maps, the report,
and walls/ with three of the camera's own full-size pictures of each wall. ZIP CALIBRATION (in the
wall test, or Zip this scanner's calibration under Depth) packs it into one file next to it, with the
serial hidden when the Capture box says so. Load saved walls brings the walls back to fit again, also
from an older version of the app: a 0.4 calibration is refitted for the stripes without new walls.

Optional: tick I measured the picture's width and type how wide the picture is on the wall
at a known distance. Without it, the lens is guessed from Creality's spec (200 mm across),
which only affects sideways sizes in exported points, not depth.

4. Depth and points

The Depth view colours the scene green in the sweet spot (18 to 35 cm), through yellow to red
outside it, with shading so shapes show. Save this view as points (.ply) writes the current
depth as a point cloud in millimetres, which MeshLab, CloudCompare or Blender can open.

5. Capturing frames, recording and playing back

Every saved picture is stamped with when it arrived, which camera, the exposure, the gain, the
auto-exposure mode and every other camera setting in force, plus its brightness, fine detail, how much
of it shows the projector's pattern, its sharpness, the light-ladder rung and the stream's own picture
number. Every setting change (light buttons, AUTO-TUNE, tests) is logged as it happens, so pictures from
before and after a change never get mixed up.

Save frame now (Capture panel): one picture from each running camera.
RECORD: every picture from every running camera (camera B joins when the A + B view starts it). every saves only every Nth picture for long recordings.
Notes: type e.g. "covered camera A" and press Add note; it is stamped on the next picture and kept in the timeline. With nothing recording, it goes on the next capture.
Hide the scanner's serial (on by default) masks it in captures and in test reports.

Each capture is a folder captures/capture_<date>_<time>_<name>/: the camera's own JPEGs (no quality lost)
in frames/, frames.csv (one row per picture with all the stamps), events.jsonl (settings snapshots,
every change, notes) and session.json. Source > Play back a recording... plays one back as if it were
the scanner. The capture code is shared with Who are yoUSB? (lizard_framecap.py); see
docs/framecap-in-lizard-scanner.md.

6. Diagnostics

Diagnostics opens one window with every check. Point the scanner at a plain wall 20 to 30 cm
away and press RUN QUICK CHECKS (about 10 seconds):

Check	What it tells you
USB connection	Both cameras there, at USB 2 speed, on the right driver, not behind an extra hub (Linux)
Camera A video	Pictures a second, late pictures, whether the stripe pattern is in every picture (or the lights pulse), picture sizes
Video modes and settings	Every mode and setting both cameras offer (saved in the report)
Serial number	The scanner's serial, read the way Creality's app does
Projector and room light	How much of the view shows the stripe pattern, how strong it is, how much infrared is in the room (judged between the stripes; sunlight swamps them), anything blown out
Depth speed	How long one depth picture takes on this computer

and, one at a time:

Check	What it tells you
Sensor map	Runs camera A alone, B alone, then both, 3 s each; measures each camera's rate, stripe pattern, colour and pulse, and asks which light you saw each time. Answers "which camera does what"
What is camera B?	Streams camera B alone (at a 1 ms flash): colour or grey, does its light pulse. On the owner's Lizard it is the camera with the white ring
Flat wall check	After the wall test: how flat a wall comes out, how far away, and (with a tape-measured distance) how far off. Also spots lens bending at the edges. The best test of a calibration
Light test	Steps the flash from 0.1 ms to 1 ms while you watch the ring, then asks what you saw
Gain test	Holds the flash at 1 ms and steps the gain: if the ring changes, the firmware ties the LEDs to gain too

Save diagnostics report (.zip) puts the results, the settings dumps, sample pictures, the
calibration report and the light / gain test answers in one zip in reports/, with the serial
hidden if you like: ready to attach to a GitHub issue.

Looking for Creality's own calibration? See
docs/research/calibration-hunt.md and the read-only Windows
script tools/Find-CR-Scan-Calibration.bat (untested).

More screenshots



Scanner off: static until the Lizard is plugged in	Pattern only: what depth is made from

The plain look (`--plain`, or Look: Plain)

HOW_IT_WORKS.md: what the app reads, changes and never does; the maths.
DESIGN_NOTES.md: findings, decisions, measurements, what is untested, what next.
INTEGRATION.md: putting the Lizard into Scantastic.
docs/research: the USB research behind the camera control.
CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, THIRD_PARTY.md.

Required Notice: Copyright Matthew Armstrong (https://github.com/The-Dorkknight)

Source code: The-Dorkknight/lizard-scanner on GitHub

SimpleCAD

Matthew Armstrong — Mon, 19 Oct 2026 20:33:23 +0000

Source-available · Non-commercial · Licensed under the PolyForm Noncommercial License 1.0.0 · Copyright Matthew Armstrong · No warranty, no liability: use at your own risk. Free for personal, hobby, study and other non-commercial use; commercial use needs my separate permission. Not legal advice. See THIRD_PARTY.md.

Early release (0.12.0). Tested in FreeCAD 1.1.4 on Linux. SimpleFlow's RUN button has been run for real against OpenFOAM v1912 (ESI) only; OpenFOAM Foundation 13, Windows and Mac are not tested yet; see RESEARCH.md. SimpleStress results are a quick check, not a certified analysis.

FreeCAD made simple: one pack, four workbenches.

SimpleCAD: a decluttered, Fusion 360-style sketch-and-solid workbench. FreeCAD's screen is full of tools most people never touch; SimpleCAD hides them (nothing is removed) and puts sketch → solid front and centre, with one big red button that always does the next obvious thing.
SimpleStress, SimpleFlow, SimpleSnap: foolproof, step-by-step simulations (will it break? how does air or water move? put the parts together). Each locks you into a short numbered pipeline: you can't skip a step, every refused click explains itself in plain English, and the same big red caution-tape button runs the next thing.

	Ask it	You do
SimpleStress	Will my part break?	Pick one part or several, tap a material tile for each (PLA, PETG, ABS, steel, stainless, pine, oak, plywood...), say which way up it was printed or which way the grain runs, bolt parts together with virtual M3-M6 bolts (no holes needed), paint the faces that are glued or bolted, pin holes, click where it gets pushed (a small spot, shown as a twinkling red disc, or the whole face), say how hard in N, kg or lb, tilt the push with two sliders, press RUN. You get STRONG / PROBABLY OK / RISKY / WILL BREAK and a red dot on the weakest spot.
SimpleFlow	How does air or water move round or through it?	Choose AROUND (a wind tunnel is built for you) or THROUGH A HOLE (click the rim of each opening: IN or OUT; the water inside is worked out for you), pick air / water / oil, set the speed and tilt the wind. It picks laminar or turbulent for you and builds the CfdOF case.
SimpleSnap	Put these parts together.	Like Lego: click a peg, hole or flat face; it lists what fits (pegs into matching holes, flat onto flat), you choose STUCK / SPINS / SLIDES, press SNAP IT. The peg goes all the way in and the part lands the right way up.

All screenshots are real FreeCAD 1.1.4 windows (Linux, virtual display, scripted clicks), except the deck close-ups deck.webp / swirl.webp, which are renders.

SimpleCAD

Features

Brushed-aluminium instrument panel: the deck is a screwed-on brushed-metal plate with engraved, recessed modules (MODE · CONFIRM · VIEW · SYSTEM), machined keys with indicator LEDs and a green phosphor readout; SimpleCAD's tool rows get the same metal and keys. The grain is a seamless generated tile (tools/make_brushed_alu.py), so it's all offline. Turn the tool-row styling off with ALU_TOOLBARS = False.
The big red button (in caution tape, shortcut Ctrl+Enter) does the next obvious thing:
- ✏ SKETCH: sketch on the selected face, or edit the selected sketch. With nothing selected, the three planes appear in the 3D view: click one, or press the big TOP / FRONT / SIDE buttons. No side-panel list to hunt through.
- ✔ FINISH SKETCH: close the sketch and leave it selected, so Extrude / Revolve / Loft is one click.
- ✔ OK – FINISH STEP: when a tool like Pad or Fillet is open, press its OK button.
Acid-green ACTIVE badge with rising bubbles shows whether you're in SKETCH, SOLID or TOOL mode.
🎯 SNAP TO FACE: look straight at the selected face (or the sketch you're in) and zoom to it.
⏎ ENTER button: pulses red whenever a tool (Pad, Pocket, Fillet...) is open and ready to confirm; click it, or just press Enter on the keyboard. (Enter is left alone in sketch mode, where it confirms typed dimensions.)
Whole-solid tools (Solid toolbar): New body (works from the start page too), Duplicate, Move / turn (drag arrows and rings), Combine, Subtract (first click kept, the rest cut away) and Intersect. Every result is a new body you can keep sketching on; originals are hidden, not deleted. Each says in plain English why it won't (e.g. "These solids don't touch, so they can't become one solid").
Make component: select bodies that belong together (a lid and its knob, a case and its clips) and they become one component (a folder that moves as one piece, like a Fusion 360 component). Nothing moves on screen. SimpleSnap snaps a component as one part. Select a component before New body to start a body inside it.

Light on old PCs: the deck is drawn once and reused, and the badge bubbles and ENTER pulse only animate briefly when something changes, so FreeCAD sits at about 3 % CPU when idle (0.9.3 kept a core about 40 % busy).
Sketch on a solid, snap to it: a new sketch on a solid gets that solid's edges in the sketch plane as pink reference lines (like Fusion 360), so your lines snap to them and can be made coincident. Use solid edges and Project (click any other edge) are first in the sketch tool row.

Only the everyday tools, on their own row under the deck, and the row swaps automatically between sketch tools and solid tools. On a smaller screen (e.g. a 1366 px laptop) the labels drop to icons only, so no tool falls off the end (hover for its name). Optional auto-extrude after finishing a sketch.
⋯ More tools: every Part Design / Sketcher command, plus "Show all hidden toolbars" and a jump to the full Part Design workbench.
Stays put: FreeCAD 1.x jumps to the Sketcher workbench when you open a sketch, and to Part Design whenever a Pad/Pocket/Fillet... dialog opens. SimpleCAD hops straight back without resetting anything (Declutter, deck and buttons stay as they were), and steps aside if FreeCAD ever keeps fighting it.
Tidy panels: model tree, task panel, report view and Python console become tabs on the left, and the Tasks tab comes forward when a dialog opens.
🧭 Navigation readout (the green phosphor display) cycles navigation styles (all orbit around the centre of the screen unless noted):
- Fusion Trackpad: two-finger swipe pans, Shift or Option + two-finger swipe orbits, pinch zooms, two-finger double-tap fits everything; two-finger click-drag also orbits.
- TinkerCAD: right-drag (two-finger click-drag) orbits, middle-drag pans, wheel zooms.
- FreeCAD Touchpad: FreeCAD's own touchpad style.
- Fusion Mouse and Cursor Mouse (orbit around what's under the mouse) need a mouse with a middle button, so on a Mac the button skips them; they're still in More tools → 🧭 Navigation.
- Reverse trackpad directions or restore FreeCAD's original navigation from the same menu.
🌀 Rainbow swirl: the selected face gets a smooth, see-through rainbow spiral so you can always see what's active (opacity: SWIRL_OPACITY). It animates gently (10 fps) and freezes to a static swirl by itself if the PC struggles; toggle it or make it static in More tools → 🎨 Look.
🌈 Rainbow faces: every face gets its own bright, see-through colour, updated automatically after each Pad/Pocket (toggle in More tools → 🎨 Look; transparency and colour strength at the top of SimpleCADDeck.py).
Looks: solids go even more see-through while you sketch. 🌙 Luminous (high contrast: near-black background, glowing cyan solids, neon selection) or ☀ Clean (light, soft blue-grey). Originals are backed up; More tools → 🎨 Look → Restore puts them back.
The look stays in SimpleCAD. Switch to SimpleStress, SimpleFlow, Part Design or any other workbench and your solids get their own colours back and FreeCAD its own background; the look returns when you come back. SimpleSnap is the exception: it assembles the same bodies you model, so they keep SimpleCAD's look there.
DECLUTTER key (amber LED when on): hides every remaining toolbar, panel and the status bar (never the workbench switcher). Press again to undo. Nothing it hides is remembered by FreeCAD, so a restart, with or without SimpleCAD, always brings everything back.
Opens in SimpleCAD: FreeCAD starts in SimpleCAD, and a new Part Design document (e.g. the Start page's Parametric Body) opens in SimpleCAD too. Turn off with More tools → Start FreeCAD in SimpleCAD (your previous start workbench comes back). The LUMINOUS key (green LED) switches the high-contrast 3D view.

Step by step

Start FreeCAD and pick SimpleCAD (it opens there by default).
Click the big red button (or Ctrl+Enter) with nothing selected, then click TOP / FRONT / SIDE in the 3D view.
Draw, then press the button again to finish the sketch; press Extrude (or let auto-extrude do it).
While a tool (Pad, Pocket, Fillet...) is open, press Enter or the ⏎ button.
More tools holds everything else, including Show all hidden toolbars and About.

Customise

Everything tweakable is at the top of SimpleCADDeck.py: which tools appear, icon size, colours, themes, navigation presets, trackpad speeds and the bubble animation.

The simulations

SimpleStress: PARTS > MATERIAL > DIRECTION > BOLTS > HOLD > FORCES > RUN > RESULT

The only solid in the document is picked automatically. Ctrl+click several solids to test them bolted together.
Materials are big colourful tiles (drawn in code, no image files): 3D printed (PLA, PETG, ABS, ASA, nylon, polycarbonate, resin), metal (mild steel, stainless, aluminium, brass), wood & board (pine, oak, plywood, MDF) and acrylic. Each shows its strength along and across its weak or strong direction.
DIRECTION (only when it matters): how it sat on the printer (flat, on its side, on its end, or click the face that was on the bed), which way the grain runs (or click the end grain), or which way a sheet's thickness runs. A blue arrow shows it in the 3D view. The stiffness and strength then really depend on it: a PLA bracket printed on its end can be half as strong as one printed flat, and the result tells you when "layers pulled apart" is the weak spot.
BOLTS (several parts only): pick M3, M4, M5 or M6 and stainless A2-70 or steel 8.8, press PLACE BOLTS and click where each bolt head goes. The bolt runs straight through into the part it touches; holes are optional. A bolt and nut are drawn in the 3D view; click one again to remove it. Each bolt is checked for stretching, shearing, its head or nut pulling through the part, and crushing the hole wall, and the result lists every part and every bolt. Parts touch only where bolted (cautious).
GLUE = stuck solid. PIN = a bolt through a round hole: it can turn but not slide off. A single pin on its own is refused (it would swing like a door).
Forces: SPOT (default): click exactly where it pushes; the force goes on a small circle there (set its size, e.g. a finger is about 15 mm, an M4 washer 9 mm), shown as a red twinkling disc. Click again to move it. WHOLE FACE: paint faces and the push is spread over them. Set how hard in N, kg or lb (kg/lb = the pull of that weight hanging on it; newtons always shown; your unit is remembered), PUSH IN or PULL OUT, then TILT (0 straight, 90 sideways) and SWING (which way it leans) with a live compass and a red arrow. Optional self-weight.
The part wears its material in the 3D view: layer lines the way it was printed, wood grain along the grain, brushed metal, so a wrong direction is easy to spot.
A face can't be both held and pushed. Nothing runs until something holds it and something pushes it.
The mesh is coarsened automatically so older PCs (7th-gen Core i3) cope.
CLEAN UP removes everything the study added, including FreeCAD's own result objects.

SimpleFlow: PART > KIND > FLUID > FLOW > CHECK > RUN > RESULT

AROUND builds a wind-tunnel box aligned with the wind (3 lengths upstream, 8 downstream, 3 each side), cuts your part out, and labels inlet, outlet and slip side walls.
THROUGH A HOLE: pick the part with the hole or channel in it (a drilled block, a pipe fitting, a manifold). Every opening on a flat face is found and shown as a grey disc. Tap IN or OUT next to each, or turn on IN / OUT and click the rim of the hole (or its inside wall near that end: the nearest end is used, never the whole wall). The fluid inside is worked out for you; if the channel also comes out somewhere you have not marked, it names that opening instead of letting the water leak. Unrelated holes (e.g. mounting holes) are ignored. Several inlets may face different ways.
THE PART IS THE FLUID: if you modelled the water itself (a solid shaped like the inside of the pipe), paint the faces where it enters and leaves.

CHECK shows the Reynolds number and whether it will be laminar or turbulent, and refuses air above 100 m/s (beyond what this setup can model).
RUN is one green button, like SimpleStress's: it builds the CfdOF case, meshes the part (Gmsh), runs OpenFOAM on every core, with a live progress line ("Solving, step 120 of 2000") and a red STOP that really ends the solver. When it finishes it jumps to RESULT. Nothing to open in CfdOF any more (small MESH PANEL / SOLVER PANEL buttons stay for experts). RESULT reads the solver log: SETTLED, STILL RUNNING, FINISHED BUT NOT SETTLED, or BLEW UP (with advice), plus how many cells and how long it took.

SimpleSnap: PARTS > BASE > SNAP > DONE

Tick parts to add them. Your own bodies go into the assembly, no copies are made: snapping moves the real part, so SimpleCAD and SimpleStress see it where it was snapped. Parts stay where they are; one that overlaps another is slid aside first.
Components: bodies that move together (a lid and its separate knob) can be added as one component (select them, then + ADD SELECTED AS ONE COMPONENT), or made beforehand with SimpleCAD's Make component. Each body on its own is its own component.
An assembly already in the file is picked up again when you come back (also after reopening the file).
START AGAIN puts every part back exactly where it was (same place, same folder) and splits components SimpleSnap made back into their bodies.
The base is fixed to the table (first part by default).
Click a face on the part you want to move. Matching faces on other parts are listed best-first (a perfect fit is chosen for you). Choose STUCK, SPINS, SLIDES, SPINS & SLIDES or BALL JOINT where it makes sense, then press the big red SNAP IT.
OTHER END pushes a peg in from the other side of a through-hole; FLIP LAST, UNDO LAST.
Snapping two parts that are both already attached is refused (it would jam the assembly). NEXT unlocks only when nothing is loose.

Files

Path	What
`InitGui.py`, `SimpleCAD*.py`, `icons/`	SimpleCAD itself (deck, solid tools, trackpad, swirl, metal panel)
`SimpleStress/`, `SimpleFlow/`, `SimpleSnap/`	The simulations (each: `InitGui.py`, `Boot.py`, `UI.py` screens, `Logic.py` plain-Python rules, `Backend.py` FreeCAD calls)
`simplewiz/`	The simulations' shared core: step-locking wizard, caution-tape panel, face picker, geometry, 3D overlays
`install.py` + launchers	Installer window (install, start FreeCAD, check, uninstall)
`tests/`	Unit/UI tests (no FreeCAD needed) and `tests/freecad/` scripts that run in real FreeCAD
`RESEARCH.md`	Sources, measurements, decisions, and what is not verified yet
`HOW_IT_WORKS.md`	What it reads, changes and never does

Build and test

Nothing to compile. The heavy work is done by FreeCAD, CalculiX, Gmsh, OpenFOAM and FreeCAD's assembly solver.

pip install -r requirements-dev.txt                    # PySide6, only for the tests
QT_QPA_PLATFORM=offscreen python3 -m unittest discover -s tests
# real FreeCAD (Linux, AppImage extracted to ./squashfs-root):
FREECAD=./squashfs-root/AppRun tests/freecad/run_all.sh

Version

One version for the whole pack. It is in SimpleCAD's About box, the deck's tooltip and the status bar, in every simulation panel's title and status line (e.g. SimpleStress 0.12.0 (Built 2026-10-16 00:58)), and in python3 install.py --version.

Source code: The-Dorkknight/simplecad on GitHub

A Bonding Experience- The open-source new frontier of Z-delamination resistance.

Matthew Armstrong — Tue, 13 Oct 2026 15:19:35 +0000

The open-source new frontier of Z-delamination resistance

A hobbyist's field guide to Z-strength in FDM printing without tripping over patents, and a defensive publication of PinLoK (pinned infill).

By Matthew Armstrong (The-Dorkknight), United Kingdom. First published 13 October 2026.

📄 Read it: PAPER.md · PDF · web page

Every strength number for my own ideas here, including Shift-LoK, FlatLock and PinLoK, is theoretical: it comes from a 2-D computer simulation with known blind spots (paper, section 3), not from printed and tested parts. They are not product claims and say nothing about anyone else's products or patents. Real-world numbers quoted from others are linked to their sources. Not legal advice.

In one minute

Printed parts snap along their layers. The famous fix, staggering walls by half a layer ("brick layers"), is patented in the US. I went looking for every way to get stronger layers without beads of different heights, ran twelve ideas through a strength model, and wrote down what happened, failures included.

Idea	Simulated result across the layers (theoretical)	Verdict
"Loopholes" (variable first layer, smaller or multi-phase staggers)	about the same as normal; still needs different bead heights	geometry doesn't care about wording
Different layer height per wall	−1 to −11 %	weaker
FlatLock (fat/thin walls)	−4 to −17 %	weaker
Squish-LoK (over-extruded squish bead)	−8 to +1 %	nothing to fill
Squish-KeyLoK (keyed gaps)	−19 to +3 %	keys snap off
Wide inner walls (about 1.5 × nozzle)	+2 to +9 %	partial success, just a slicer setting
PinLoK pinned infill	+16 to +27 % against solid infill of the same weight	best result; costs print time

PinLoK builds on Oak Ridge National Laboratory's published Z-pinning. Every few layers the nozzle stops over half of the open gaps in Grid infill and pushes a blob of plastic down into each one; the other half get theirs next time, so the joints never line up. A potato mode keeps each push to about a second for stock printers like the Ender 3. A late discovery: pins that end half-way through a layer, not on a layer line, did far better in the simulation.

Why it's published

To keep it free. Once a method is published, nobody can validly patent it afterwards. Section 9 of the paper discloses PinLoK and its variations in buildable detail, and the methods are dedicated to the public.
To bring makers together. Open notebooks let tinkerers build on each other's work instead of repeating it. Print the test plan, post your results as an issue or discussion, fork it, improve it: everyone who contributes gets credited in the next version (paper, section 11).
To save you the dead ends. Most of the ideas here didn't work. Now you know without trying.
Selfishly: more cool 3D-printing techniques come back from the community, and I am now 22.713333…% more employable. High-efficiency synergy.

What's in here

Folder	What
`PAPER.md`, the PDF, `docs/`	The paper as Markdown, PDF and a web page
`figures/`	Every figure
`pinlok/`	The PinLoK G-code post-processor (Python 3.8+, no dependencies): `python3 pinlok/engine.py file.gcode --mode potato`
`tests/`	Its tests: `python3 -m unittest discover -s tests`
`model/`	The strength model and every result file (needs numpy, scipy, matplotlib)
`PUBLISHING.md`	How this was published, and what makes it count as published

The full app (LoK Walls: FlatLock, PinLoK and a locked brick-layer pattern, with installers for Cura, PrusaSlicer and OrcaSlicer) is in a separate repository, to be published after ADDMAN, the brick-layer patent holder, has been asked. I haven't contacted them yet; I intend to.

Cite

See CITATION.cff (GitHub shows a "Cite this repository" button). Once archived, the DOI goes here: DOI to be added.

Source code: The-Dorkknight/a-bonding-experience on GitHub

SimpleMesh

Matthew Armstrong — Sun, 11 Oct 2026 08:45:17 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN · version 0.5.0-wip · pre-release

About the screenshots: they are the real Blender 4.0.2 window with SimpleMesh loaded, captured on a virtual display (software rendering) while a script moved the mouse and pressed keys (tests/gui_session.py). No person, and no child, has used this version by hand yet, so how it feels is unproven. See what is tested.

A Blender add-on that turns Blender into a plain make-and-print workbench. No scenery, no animation timeline, no game-asset tooling. It has two levels:

Easy mode (what Blender now starts in): big picture buttons aimed at a ten-year-old. Build things out of shapes, your own drawings, words and clay, colour them in, press Print!.
The panel: big buttons across the top of the 3D view, there in every mode, for editing STL files exactly: lay flat, move, turn, size, pull a face, cut, drill, measure, mould like clay, with millimetres. It is the same idea as SimpleCAD's deck: a big red button that does the next obvious thing, a green badge that says what is active, and keys for the look.

It is the Blender sibling of SimpleCAD.

Easy mode

To make something: click a picture, move the mouse, click to put it down. A shape sits on whatever is under the mouse: the floor, or the top or side of another shape, so things stack and stick the way you expect.

Left side: things to add
Block, Ball, Tube, Cone, Pyramid, Roof, Ring, Star, Heart	Ready-made shapes.
Draw	Hold the mouse button and draw a loop on the floor. It becomes a solid shape. Wobbly lines, crossed lines and scribbles still give something solid.
Words	Type a word or your name and get 3D letters.
Clay	Squish and pull the chosen shape (or a new ball) like clay, then press Done. Turn on Mirror for faces and creatures.
Ideas	Start from a snowman, house, rocket, robot or car made of shapes, then change it.
Open	Load a model file somebody else made.

To change a shape: click it. Drag it to move it. It has six dots:

Dot	Pull it to...
white (top corner)	make it bigger or smaller
red / green / blue	make it longer / wider / taller
orange	spin it round
purple	tip it over

Along the bottom
Undo / Redo	Go back a step. Nothing can be broken.
Copy / Bin	Another one the same / throw it away.
Hole	Turns the chosen shape into a hole (it goes red). Push it into another shape; Glue or Print! cuts it out.
Glue	Sticks the shapes together into one.
Save	Keeps your project so you can carry on another day (it reopens in Easy mode).
Colours	Colour in the chosen shape. (Colours are for you; a printer prints in whatever plastic is loaded.)
Print!	Cuts out the holes, glues what touches, repairs everything, sits it on the bed, tells you if it is too big, and saves the file for the printer.

Bottom right: arrow buttons turn the view, + and − zoom, the middle one shows everything. You can also drag with the right mouse button to look around.


What Blender looks like when it starts	A ball being put on top of a block
The six dots on the chosen shape	Pulling the blue dot: taller
Draw a loop on the floor...	Ideas: ready-made starters

The Easy key on the panel turns Easy mode off and on. With it off you select models by clicking and use the panel's tools described next. To make Blender start with it off, untick Start in Easy mode in the add-on's preferences.

What "anything you can imagine" really means here: anything you can build from those shapes, your own drawn outlines, letters and clay, stuck together and with holes cut out. That covers a lot (characters, vehicles, buildings, name tags, cookie cutters, creatures) but it is not everything: no screw threads, no exact engineering fits, and very thin clay shapes may not print.

The panel (big buttons)

Part	What it does
The big red button	The next obvious thing. Normally MOULD LIKE CLAY. While a tool is on: FINISH that tool. While moulding: DONE. In one of Blender's own modes: BACK TO THE MODELS. In Blender's own Sculpt Mode before the model is ready: GET READY TO MOULD.
The green badge	What is active right now: SELECT, EASY, LAY FLAT, CLAY: PULL...
FIND MODEL	Centres the view on the model (same as F).
Tool keys	Lay flat, Move, Turn, Size, Pull face, Cut, Drill, Measure, Open, Save, Undo, Redo. The key of the tool that is on has its light lit. While moulding they become the seven brushes plus Brush +, Brush - and Mirror.
Easy	Picture buttons on or off.
Luminous	Switches between the dark, high-contrast look and the light, clean one.
Hide clutter	Hides Blender's own menu rows and status bar; press again to bring them back. The panel stays.
More tools	Exact numbers, shapes and holes, check and repair, view settings, Look (below), and Report a problem.

The panel is drawn inside the 3D view (Blender's own header rows cannot hold big buttons), ends short of the right edge so Blender's view ball stays free, and shrinks its buttons on a narrow window. Hover over a button and a line under the panel says what it does. Switch it off in More tools ▸ Big-button panel and the tools go back to the thin strip in Blender's header.


Lay flat is on: its light is lit, the red button says FINISH LAY FLAT	While moulding: DONE, and the brushes
The Clean look	Hide clutter: Blender's rows are gone

Look

More tools ▸ Look (also in the strip's View pop-up):

Luminous (near-black background, cyan models, orange outline), Clean (light background, soft blue-grey) or Blender default. The Luminous key on the panel switches between the first two.
Rainbow: every model gets a colour of its own, which shows at a glance which parts are separate.
Show the triangles: the triangles of the STL drawn on the model.
See-through, Show flipped faces (red), Show size on the model.

The tools

Open an STL. It arrives in millimetres at a sensible size (a 5200 mm monster is divided by 10 until it fits your bed), sitting on the bed, in the middle of the view. Its size and "fits the bed" are written in the top-left corner all the time.
Pick a tool on the panel, then do it on the model. The view shows what a click will do before you click. Orbit and zoom keep working. Esc or right-click leaves the tool. Ctrl+Z undoes.
Save writes a millimetre STL as <name>_edited.stl.
Lost the model? Press F (or Find).

Tool	What you do	Extras
Lay flat	Move over the model: the flat face under the mouse lights up. Click: that face sits on the bed.	No Edit Mode.
Move	Drag a model: it slides across the bed.	Shift+drag lifts it. Arrow keys 1 mm (Shift 10, Ctrl 0.1). D = drop to bed, C = centre.
Turn	Drag a model sideways: it spins in 15° steps and is put back on the bed.	X / Y / Z choose the direction. Arrow keys = 90°. Type an angle + Enter. Shift = fine.
Size	Drag away from the model = bigger, towards it = smaller. Or type the longest side in mm + Enter.	X / Y / Z stretch one direction only. Ctrl = whole millimetres. Scale stays 1.0.
Pull	Point at a flat face (it lights up) and drag it out or in: the part gets longer or shorter. Or point and type mm + Enter.	Steps of 0.5 mm; Ctrl = whole mm; Shift = free. Minus key = inwards when typing.
Cut	A red plane follows the mouse over the model; click to cut there. Or drag a line across the model to cut along it.	X / Y / Z direction. Type a height in mm + Enter. K = keep both / one side. L = lay the cut faces on the bed. Cuts are capped.
Drill	A red circle follows the mouse on the surface; click to drill a round hole.	Type the diameter + Enter, or + / −. T = through / blind, [ ] = depth. Ctrl = centre of the face.
Measure	Click two points.	Snaps to corners. Shows the distance and its X / Y / Z parts.

Clay: mould it like clay

Clay is for free-form changes: click a model, press the red MOULD LIKE CLAY button (or the Clay picture in Easy mode), and the panel's keys become seven brushes. Press on the surface and drag. Choosing Sculpt Mode from Blender's own mode menu ends up in the same place: SimpleMesh does the Clay set-up by itself.

Brush	What it does
Pull	The clay follows the mouse and stretches out. Pull a lump, a horn, a handle out of a flat face.
Build up / Push in	Rub to raise the surface / press it in.
Shift	Slide an area sideways without stretching it.
Inflate	Swell outwards in all directions.
Smooth / Flatten	Rub out lumps / level an area.

Brush Size is in millimetres and stays the same at any zoom; it starts at a fifth of the model. Brush + and Brush - on the panel change it (or F, then move the mouse). Holding Ctrl does the opposite, holding Shift smooths, Ctrl+Z undoes a stroke. The read-out shows how many triangles the model has and warns in red when it is getting heavy. Press the red DONE button to go back to the normal tools.

Underneath it is Blender's own sculpting engine, set up for STL work: the model is first given small triangles everywhere (its shape does not change) because an STL's big flat triangles have nothing to mould; more are added under the brush as you work; mirror symmetry is off; and when you press Done the flat areas you did not touch are merged back into big triangles so the file stays small. Detail (the size of the new triangles, in the header row) cannot be set finer than a thirtieth of the brush: a big brush with a tiny Detail makes Blender cut hundreds of thousands of triangles in one drag and stop answering.


Pull: point at a flat face...	...and drag it: +10 mm
Clay ▸ Pull: a horn pulled out of a flat face	Clay ▸ Push in

Pop-ups in Blender's header row (and under More tools on the panel) hold the things that need numbers or are used less often:

Numbers: ÷1000 ÷100 ÷10 ×10 ×1000, inch ↔ mm, set the longest side, exact X/Y/Z, drop / centre / auto lay flat, 90° turns, mirror, hole and cut settings.
Shapes: add a block, cylinder, sphere or cone sized in mm. Make it a hole turns any shape into a red wire "hole"; Cut the holes out removes every hole from whatever it touches (no "select the cutter, then the base"). Weld together, separate loose pieces, copy, delete.
Repair: Check (triangles, volume, surface, holes, inside-out faces), one-click Repair, Simplify.
View: standard views, show everything, looks (Luminous / Clean / Blender default), show flipped faces, laptop navigation (no middle button needed), printer bed size (presets for FlashForge Adventurer 5M, Bambu Lab A1, Creality Ender 3 V2).


Cut: the plane follows the mouse	Hole: the circle follows the mouse
Cut: drag a line across	Measure
Size: drag, or type	The Numbers pop-up
A 5200 mm STL after Open: shrunk to fit, centred	Open: choose the file's units here

Why the tools are like this, and which existing add-ons and programs they were modelled on: docs/DESIGN.md.

What is tested and what is not

Tested in a real Blender 4.0.2 window (virtual display, simulated mouse and keys, 114 checks, tests/gui_session.py; the first part drives the tools through the thin strip with the panel off, the last part drives the panel): Easy mode as a scripted child's session: Blender starts in it; Block is picked up and put down; a Ball is put on top of the Block and lands on it; clicking selects; pulling dots makes the block taller, bigger and spins it; dragging slides it; colour, Copy, Bin; a loop drawn with the mouse becomes a solid; Ideas places a rocket; Glue makes it one closed model; Undo; the arrow buttons and right-drag turn the view; the Clay button and Done; Print! glues, repairs, sits everything on the bed and opens the save box; a saved project reopens in Easy mode. Then the strip tools: start-up tidy (one 3D view, millimetres, two workspace tabs); import of a 5200 mm STL lands centred and sensibly sized on screen; view re-centres after scaling; F finds a model 4.7 m away; every strip tool by click/drag/keys (lay flat by hover+click, move by drag and arrow key, turn by drag and by key, size by typing and by drag, cut by click and by dragging a line, pull a face by typing and by dragging, hole with typed diameter, measure); Clay: entering from the strip, millimetre brush size, a Pull stroke stretching a flat face from 20 to 39 mm, switching to Push in, Ctrl+Z after the first stroke staying in Clay and taking back just that stroke, redo, Done merging flat areas and leaving the model watertight; Sculpt Mode entered the way Blender's own mode menu does it being noticed, set up automatically (small triangles, automatic detail, the Pull brush in millimetres) and a drag then pulling the block from 20 to 39 mm; undo of a tool step; switching tools from the strip while a tool is on; the four pop-ups and the Open file chooser appear. The panel: its mouse watcher starts by itself; a click on the Lay flat key starts the tool, lights the key and turns the red button into FINISH LAY FLAT; the red button finishes it; clicks on the panel do not reach the model behind it; the red button starts Clay and the keys become brushes; Brush +, a brush key, a stroke in the view, the Undo key (the stroke goes, Clay stays), DONE; the Luminous key; Hide clutter and back; the Easy key, a picture button under the panel, a panel tool started from Easy mode and Easy mode taking over again afterwards; a recovery copy written while the panel is watching the mouse. The installer window was driven the same way (tests/test_installer_gui.py, 20 checks): it found and questioned two Blenders, ticking and unticking rows, refusing a program that is not Blender, Install, the two options, Remove, and Open Blender all worked, and Blender then started normally with the add-on on. Plain python3 install.py and the Linux launcher script both opened the window (tests/test_install_launch.py, 14 checks, starts install.py as its own program and looks for its window). With tkinter switched off, the dialog-box version (zenity) was clicked through an install by hand-placed mouse clicks, and the terminal version picked Blender number 1 from its list.

Also tried by hand with real mouse and keyboard events (sent through the display server with xdotool, not Blender's own event simulation; Blender 4.0.2 started normally after the installer; these sessions are not part of the repository's tests): placing a block and pulling a dot; opening a 234-triangle bracket and a 327,680-triangle model through the real file chooser; Lay flat on the bracket; a long Clay Pull stroke on both; Sculpt Mode chosen from Blender's mode menu (in 0.4.2 two long drags changed nothing you could see, in 0.4.3 the set-up runs and the drag pulls a horn out); Ctrl+Z after one and after two Clay strokes; Undo pressed until nothing was left, then adding a shape; Edit Mode and Back to the models; Report a problem (which caught a real error in the first version of the undo repair). With Blender 5.0.1 and version 0.4.2, placing a block, pulling a dot and a Clay Pull stroke worked the same way; nothing later than 0.4.2 was run in a 5.x window. For 0.5.0, on a 1366 x 768 screen: the panel's keys by real clicks (Lay flat and FINISH, MOULD LIKE CLAY, Brush + three times, Build up, strokes, the Undo key, DONE, Luminous, Hide clutter, More tools and its Exact numbers pop-up, Report a problem); four fast clicks on a picture button all counting; an 82,000-triangle model opened through the file chooser and moulded with five strokes (Blender stayed under 0.9 GB and DONE took under 8 seconds on this machine's software rendering). The freeze: with 0.4.3 the same model, five strokes and then Finer everywhere left Blender not answering for several minutes at 4 GB; that button no longer exists.

Tested without a window (tests/test_headless.py, Blender 5.2.2 as the bpy module, also with numpy disabled): all the mesh work behind the tools: import sizes and units, scaling, lay flat, every Easy shape is closed and the right size; hand-drawn outlines (clean loop, overshoot, figure-of-eight, scribble) always give a valid solid; words become closed letters; each of the five Ideas goes through Print! to one watertight model that fits the bed; glue with holes; cuts with any plane (volumes add up, caps watertight), pulling faces, refining for Clay and merging flat areas again, Clay set-up including all seven brushes on Blender 5.2's brush system, drilling through and blind holes, hole shapes, weld, separate, repair, simplify, export and re-import.

Not tested: any real person using it, and in particular no child has tried Easy mode: whether a ten-year-old finds the dots, the stacking and the wording obvious is exactly what a scripted mouse cannot tell me; the Words and Save pop-up boxes themselves (the operators behind them were run); screens smaller than 1366 x 768 (the picture buttons were looked at on 1600 x 900 and 1366 x 768 only); trackpads; the two reported problems on the computer where they were reported: "a drag only changes it slightly" (0.4.3: reproduced here by choosing Sculpt Mode from Blender's own menu) and "on sculpt all controls lock up" (0.5.0: reproduced here with Finer everywhere), so in both cases I fixed something that matches the description without being able to check that it is what happened there; the panel, the look keys and every other 0.4.3 and 0.5.0 change in a window on any Blender other than 4.0.2 (on 5.2 only the windowless tests, where the panel is laid out and its buttons run but nothing is drawn or clicked); Blender 3.x and 4.1 to 4.5 in any form; the panel on high-resolution (Retina / 4K scaled) screens, on two monitors or in more than one Blender window; the recovery copy over a real working session (it was written once on demand and once by its timer); Clay on models above about 330,000 triangles and on slow computers; the dense-model path above 700,000 triangles; large real-world STLs (hundreds of thousands of triangles: hovering builds a lookup of the model first, which may pause for a few seconds); the full scripted window session on Blender 3.x, 4.2+ or 5.x (only the windowless tests ran on 5.2); a real double-click on install.py or the launcher in a desktop file manager (they were started from a command line on a virtual display; the 0.4.2 fix for "install.py shows nothing" was not confirmed on the computer where it was reported); macOS and Windows, including the Mac and Windows double-click launchers and the "Add another Blender..." file chooser box itself; flatpak/snap/Steam Blender with the installer (the search for them is written but there was none here to find); the extension-format zip; the GitHub workflows.

docs/DESIGN.md · HOW_IT_WORKS.md · CHANGELOG.md · CONTRIBUTING.md · SECURITY.md

Source code: The-Dorkknight/simplemesh on GitHub