-
-
Notifications
You must be signed in to change notification settings - Fork 0
Feature Guide
A tour of every screen and what it does.
- Library
- Variant grouping
- Model detail
- 3D viewer
- Image picker (thumbnails)
- Favorites, print queue & printed tracking
- Kit Builder
- Metadata editing & web enrichment
- Triage queue
- Collections
- Bulk editor (tags & enrich)
- Import folder
- Creators & per-creator rescan
- Settings
- Backup, restore & reset
- NSFW toggle
The main grid. Every filter lives in the URL, so you can bookmark or share a filtered view.
- Search by name, title, description, or character.
- Filters: creator (include or exclude), source site, tag, NSFW, has-image, needs-review, min star rating, favorites, in-queue, and printed. Open the Filters panel for the full set, or use the quick chips in the header (e.g. "N favorites", "N queued", "N printed") — so you can see both what you want to print and what you've already printed.
-
Negative tag filter: clicking a tag cycles through three states —
include (show only models with the tag), exclude (a
≠ tagchip; hides models with the tag), and off. Only one include and one exclude tag apply at a time. - Hide printed: the hide printed chip excludes models you've already printed (status printed), leaving queued and not-yet-printed models. It's the inverse of the printed chip, and the two are mutually exclusive.
- Sort: the Sort dropdown in the header orders the grid by Name, Date added (newest first), or Creator. The choice is captured in saved presets and remembered as your default across browsers; Prev/Next on a model's detail page walks the library in the same order. (The Recently added chip forces newest-first while it's on.)
- Recently added: a quick chip in the header filters to models added in the last N days, newest first, and cards inside that window carry a New badge. The window (3 / 7 / 14 / 30 days) is configurable under Settings → Preferences.
- Saved presets: once you've dialed in a set of filters, save it as a named preset and re-apply it with one click. Presets are stored server-side, so they follow you across browsers and devices.
- Pagination: Prev / page number / Next, with a jump-to-page box — shown at both the top and bottom of the grid so you can page without scrolling. The page size (24 / 48 / 96) is configurable under Settings → Preferences, along with the other server-side preferences (NSFW default, filter presets).
Each card shows the thumbnail, name, tags, and small action icons (favorite ★ and print-queue 🖨) that appear on hover. You can also drag a card by its hover grip onto another card to group them as variants — see Variant grouping.
Keyboard shortcuts: the grid is fully keyboard-drivable. Press / to jump to
the search box, A/D and W/S (or the arrow keys) to move the focus ring
between cards, Enter to open the focused model, and Esc to blur search or
clear the focus ring. You can also group cards from the keyboard: Tab to a
card's grip handle, Space to pick it up, the arrow keys to move it onto a
target card, then Space/Enter to group them (Esc cancels). Press ? (or
the keyboard button in the header) at any time to see the full list.
When several folders share the same character (for example a Bust, a Full size, and a Pre-supported version of the same figure), the Library collapses them into a single group card with a "N variants" badge. Click it to open the group and see each variant individually.
This keeps the grid tidy when a creator ships many cuts/versions of one model.
The scanner infers the character group from folder names — it's accurate for most layouts but occasionally gets it wrong (typo'd folder, unusual nesting, inconsistent studio naming). You can fix any mis-grouping durably, so your correction survives future rescans:
Drag-to-group from the Library (fastest for grouping loose models)
In the main Library view, hover a model card and a small grip handle appears in its bottom-left corner. Drag the card onto another card from the same creator to group them:
- Onto an existing group — the dragged model is added to that group straight away, taking on its name.
- Onto a loose card — a naming prompt opens (pre-filled with the target's display name); confirm or edit the name and both models join that group.
- Multi-select drag — select several cards with their checkboxes first, then drag any one of them to group the whole selection in a single step. The drag preview shows a count badge.
- Merge two groups — drag a group card onto another card. A confirmation asks before moving every member of the dragged group into the target group (the dragged group's name is discarded).
Grouping only works within a single creator (cards from other creators in a multi-selection are skipped), and only in the default Library view (it's off in the favorites/queue/printed/excluded views, which show flat cards).
The whole gesture is keyboard-accessible: Tab to a card's grip, Space to
pick it up, arrow keys to move it onto the target, Space/Enter to drop and
group (Esc cancels). Screen readers announce the pickup, the card you're over,
and the result.
From the group view (fastest for fixing a whole group at once)
Open a group card to see all its variants. The group view manages the whole group as well as individual variants:
- Rename the group — click the group title in the header to edit it in place. Saving renames every variant in the group and takes you to the renamed group.
-
Bulk actions — tick the checkbox on each card you want (or Select
all), then use the toolbar that appears:
- Move to group — type a target group name (with existing-group suggestions); the selected models move there. Moving into a group that already exists is how you merge groups.
- Set image — paste an image URL (or a product-page link, whose preview image is used) to give every selected variant the same thumbnail. The image is downloaded once and applied to all of them.
- Set store page — paste a store/product URL to write it as the source link on the selected variants. Variants of one figure usually share a single store listing, so this fills the store page across them in one step. It applies to exactly the variants you've ticked (overwriting any existing link on those) and leaves unticked siblings alone — so you can set one listing on most variants while keeping a different link on the odd one out.
- Ungroup — pull the selected models out of the group, making them standalone models in the Library.
- Per-card actions — below each card, Move to group (with name suggestions), the image button (Set as group thumbnail), and × Remove act on that one variant.
- Pick the group thumbnail — the group's Library card borrows one variant's image. By default the representative variant is chosen automatically: a variant you've favorited or queued is promoted to the front so its ★/🖨 chip shows on the group card, otherwise a variant that has a thumbnail represents the group. Click the image button under any variant to override and make it the group's display image instead — that choice is saved and survives rescans.
- Reorder within a group — drag variant cards within the group view to set a custom display order. The order persists until you reset it.
Models that move or ungroup leave the current list immediately. When the last variant leaves, the group view closes back to where you came from.
From a model's detail page
Click a model, then find the Set group button in the header (alongside Edit, Find on Web, and Split pack):
- Click Set group to open an inline input. Start typing — existing groups for that creator appear as suggestions so you can pick from a list rather than type the full name from memory. Leave the field blank and save to ungroup the model. Press Enter or click Save; press Escape to cancel.
- Once an override is active, the button changes to an indigo Group: [name] chip. Click it to change the assignment, or click ✕ beside it to clear the override (restoring scanner-detected grouping on the next rescan).
How overrides work
A group override is written to the database and applied immediately — the model moves to the new group without needing a rescan. On every future rescan the scanner sees the override and applies it instead of the heuristic, so your corrections are permanent. Clearing an override removes the record; the scanner will re-derive the group on the next rescan.
Click a card to open the model. From here you can:
- View and switch between all its preview images.
- Toggle to the 3D viewer (if it has STL files).
- Edit tags inline — click the + button next to a tag to add a tag, or the × on any tag to remove it, without opening the full edit screen. The tag list autocompletes from all tags already in your library.
- Edit metadata, tags, source URL, and the NSFW flag (full form via Edit).
- See and label each STL file (head, arm, base, etc.).
- Download all files as a zip, or open the Kit Builder.
- Add the model to one or more Collections (see below).
- See the model's Location on disk — copy the path, or (standalone only) click Open folder to jump to it in your file manager.
On any model with STL files, switch to 3D View to inspect the mesh:
- Drag to rotate freely in any direction, scroll to zoom, right-drag to pan.
- The camera auto-fits the model on load, so it's framed correctly every time.
- If a model has several STLs, use the file buttons to switch which one you're viewing.
- A size warning appears for very large files (they can be slow to load in a browser).
If the auto-chosen thumbnail is wrong (or missing), open a model and click Change image on the preview. The Set Thumbnail dialog offers:
- From Folder — every image found in that model's own folder, to pick from.
- From URL — paste any image URL; the image is downloaded and stored locally, so it keeps working even when the site blocks hot-linking.
- Clear — remove the thumbnail entirely.
To clear an image quickly without opening the dialog, use Clear image in a card's ⋯ quick-assign menu, or the Clear image button next to Change image on the model's detail page.
Three independent ways to organize what you want to print. A model can be any combination of these.
- ★ Favorite — bookmark models you love. Filter the Library to favorites with the header chip.
- 🖨 Queue — add models to your print queue. The Queue page (in the top nav) shows everything queued so you have a running "to print" list, and the nav shows a live count badge. Drag the handle (bottom-left of each card) to set your own print order; favorites always float to the top.
- ✓ Printed — mark a model as printed. This records the date and removes it from the active queue. The Queue page keeps a Recently Printed section so you can see what you've finished, and the Library has a printed header chip to filter down to everything you've printed. If you mark something printed by mistake, click Undo printed in the model header to revert it to not-printed (the print date is cleared).
You can toggle favorite/queue right from a card (hover icons) or from the buttons in a model's header. (Printed is set from the model header.)
Launched from any model's detail page. It groups that model's STL files by their part label (head, torso, arms, base…). Pick one file per part group to assemble a complete build, then copy the file list or download the selection as a zip. Handy when a model ships multiple head or pose options and you want to commit to one combination.
To make this useful, label your parts first: on the model detail page, each STL file has a small Label input with common suggestions.
Open a model and click Edit to change the title, creator, description, notes, source URL, license, category, tags, and NSFW flag.
The Source URL field has a Fetch button: paste a product page from Gumroad, Cults3D, MyMiniFactory, or Loot Studios and it scrapes the page to fill in the title, description, creator, thumbnail, and tags automatically.
There's also bulk enrichment from the Creators page (see below).
A keyboard-driven review screen at /triage for models the scanner flagged as
uncertain (needs_review). Work through them quickly:
-
→/ Space = dismiss (looks fine) -
S= skip -
←= go back
The nav shows a live count of how many models still need review.
Collections let you group models into named sets — independent of tags or creators. Use them for things like "Army project", "Current print queue", or "Gift ideas".
- Create a collection with the New Collection button.
- Rename a collection — hover the card and click the pencil icon, then type a new name and press Enter (or click Save).
- Delete a collection — hover the card and click the trash icon, then confirm. Deleting a collection does not delete any models; it only removes the grouping.
- Click a collection card to open its detail view.
Shows every model in the collection as a standard grid. To remove a model from the collection, hover the card and click the × button in the top-left corner.
There are two ways:
-
From a model's detail page — scroll to the Collections section in the right column and click Manage. A checkbox list appears; tick any collection to add the model to it (untick to remove). You can also create a new collection inline from the same panel — it's created and the model is added in one step.
-
Bulk add from the Library — select multiple models using their hover checkboxes, then click Add to Collection in the floating bar at the bottom of the screen. Pick a collection from the list that appears.
- A model can belong to any number of collections.
- Collections are included in the database backup, so they survive a backup/restore with no extra work.
In the Library, hover a card and use the checkbox to select multiple models. A floating bar appears with bulk actions across the whole selection at once:
- Add or remove tags — apply or strip a tag on every selected model.
- Add to a collection — drop the whole selection into a collection.
- Enrich — set creator, character, and/or title across the selection in one pass. Leave a field blank to leave it untouched. This is the fast way to fill in metadata for loose or badly-named imports so they become eligible for Reorganize.
Import (in the nav, at /import) brings an arbitrary folder of loose downloads, an unzipped pack, or a pile of unsorted files into the catalog without adding it as a permanent scan root — then files them into a managed library on disk. It implements the full import → enrich → organize pipeline.
A library is a scan root you've named and marked as an import destination (Settings → a folder card → set a Library name and tick Import destination). Only writable libraries can receive imported files — see Scanning & folders.
-
Pick a source folder at /import → Preview packs. This opens the
Import Preview screen (
/import/preview). - One card per pack — each immediate subfolder of the source is a pack card (files directly in the source form a single pack).
- Choose the destination Library once from the dropdown. The choice is saved as a source → library mapping: every pack under that source inherits it, and the dropdown pre-fills (but stays editable) next time.
- Enrich each pack — expand a card to set Creator, Character, Title, and Tags, then click Import. That ingests just that pack's folder as inbox models and applies the metadata.
- Move them in — a "Move N imported packs → {library}" bar files the imported packs into the destination library on disk (drift-checked, with undo). The inbox flag clears as each pack lands.
-
Quick import (whole folder) on
/importkeeps the original one-shot index of the entire source in a single pass (each immediate subdir = a creator, loose files → an_Inboxcreator) — handy when you don't need per-pack review. -
Inbox flag — un-filed imports are marked inbox; the Library's
?is_inbox=1filter shows just these. - The move step is standalone-only (Docker mounts are read-only) and requires write mode; importing and enriching work everywhere. Packs missing a creator/character (or otherwise blocked) are reported as skipped, not moved.
The Creators page lists every creator with their model count. From here you can:
- Click a creator to browse just their models in the Library.
- Rescan a single creator — a targeted scan of just that creator's folder. Because you usually add models one creator at a time, this is much faster than a full library scan. The button is disabled while any scan is running.
- Enrich from web — match a creator's online storefront listings against your local models and bulk-apply metadata (source URLs, thumbnails, IDs).
An opt-in module for tracking your paint inventory and reading step-by-step painting guides. Enable it under Settings → Painting Guides; the nav then gains Guides and Paint Shelf entries.
The Paint Shelf is a table of every paint you own (or want): search by name or code, filter by brand, line, finish, or owned state, and see a color chip for any paint with a swatch color set. Add or edit paints inline with the Add paint form.
A paint line can declare a code pattern (a regex like ^MPA-\d{3}$); paint
codes are then validated on entry, so typos like MPA-12 get caught with a
clear message instead of polluting the shelf.
If you track paints in PaintRack, import its CSV export directly:
- Import CSV shows a diff preview first — what would be added, changed, or removed — and writes nothing until you confirm. Removals are off by default behind a separate checkbox, and only ever touch paints that came from a previous import; paints you added by hand are never deleted.
- Codes that don't match a line's code pattern are listed as warnings in the preview — informational only, the rows still import.
- Export CSV downloads your shelf in the same format, and an export re-imports as an empty diff (a lossless round-trip).
The CSV has an optional seventh Color column so an import can pre-populate swatch colors, and your stored swatches are included in every export:
| Format | Example |
|---|---|
| Hex | #2A2A2A |
| RGB | "rgb(176,48,48)" |
| HSV |
"hsv(120,50,80)" (H 0–360, S/V 0–100) |
All three are normalized to hex on import. Because rgb()/hsv() values
contain commas, those cells must be quoted in the CSV. Files without the
column (like real PaintRack exports) import exactly as before, and an empty
color cell never clears a swatch you've already set — only a different,
non-empty color shows up as a change in the preview.
The Guides page lists your painting guides; open one to read it in-app. A guide is a tabbed, step-by-step recipe: per-tab value maps, numbered steps with technique tags, paint swatches drawn from your Paint Shelf (every guide only references paints you own), method cards, and a shared Thinning Reference. Each guide carries its own theme, so it looks the same as the standalone HTML version.
- New guide (button, top-right of the Guides page) creates a guide from scratch, and Edit (button, top-right of an open guide) changes its title, subtitle, scale, franchise, technique tags, creator credit, paint lines and other header details. Edit content (button, top-right of an open guide) opens a structured editor for the guide's tabs, phases, steps and paint swatches — add, remove and reorder each level, and pick swatch paints from your shelf. Saving content replaces the guide's tab tree; saving metadata leaves the content untouched.
- Mix swatches — a step swatch can reference a blend like "Paint A + Paint B (3:1)". These import from guide HTML, render as a single blended-dot chip in the reader, and round-trip cleanly back to the same notation on export.
-
Import guide (button, top-right of the Guides page) uploads a guide HTML
file — click the file input, or drag and drop an
.htmlfile onto the dropzone. It lands as a draft for review — never auto-published — and shows an import report: how many swatch paints matched your Paint Shelf and any content the importer couldn't map.- If some paints didn't resolve, the importer shows a Paint resolution step before committing. For each unresolved paint you can: Map it to an existing shelf paint, Force-add it straight to your Paint Shelf (pre-filled with any swatch color from the guide), or Skip it (the swatch is dropped). Once every paint is resolved or skipped, the guide imports.
- Add missing paints to your Paint Shelf before importing if you'd rather not use the resolution step, or just re-import after the shelf is updated.
- Publish / Unpublish and Delete (buttons, top-right of a guide) control a guide's lifecycle: drafts stay flagged in the list until you publish, and delete removes the guide and all its tabs, steps and swatches after a confirmation.
-
Print (button, top-right of a guide) expands every tab and sub-tab into
one continuous, print-styled document — the whole guide in one pass. The print
stylesheet preserves dark backgrounds and paint chip colors (
print-color-adjust: exact) so swatches render correctly on paper and in PDF. -
Export PDF (button, top-right of a guide) renders that same print-styled
document to a downloadable PDF — handy for sharing a guide or printing it
later. In Docker the renderer is bundled and ready to use; the standalone
build needs a one-time
playwright install chromium(see the install notes) the first time you export. - Model links tie guides to your library both ways: a model that has a guide shows a Guide badge on its Library card and a Painting guide button on its detail page, and the guide links back to its model.
Settings → Library Tools → Reorganize Library (or /reorganize) tidies your
files on disk to match a folder template — by default
{creator}/{character}/{title}.
- Preview first. The page shows exactly where every model would move, one row each, with a move-kind chip (move / rename / case rename / in place / merge) and blocker chips for anything unsafe (collision, over-length or reserved name, unclassifiable, symlink, multi-directory, escapes-scan-root, missing files). Nothing is touched until you apply.
- Resolve flagged rows. Expand an ineligible row to supply a missing creator/character/title or add a suffix that breaks a collision or shortens an over-long/reserved name. The preview regenerates as you type.
- Apply. Tick the eligible rows and Apply. The app verifies each file hasn't changed since the preview (aborting the whole batch on any drift), moves files safely across drives, and repaths the index — packs and manual character groupings are carried along, not orphaned.
- Undo. Undo last apply reverses the batch, skipping anything you've since edited or that now sits where a file would return.
Apply moves real files, so it is standalone-only and opt-in: it stays disabled unless the deployment enables write mode and the destination is actually writable (the read-only Docker mount can never apply). Preview and resolve work everywhere.
At /settings you manage your scan roots — the top-level folder paths the app reads from. Add or remove paths, and see when each was last scanned. This is also where standalone users point the app at their drives for the first time.
If a configured folder can't be found when the Library loads — typically an external drive that's unmounted or disconnected — a warning banner appears at the top of the Library listing the affected paths, so an empty library reads as "drive unavailable" rather than "everything is gone".
It's also home to Scan Rules and Data Management (see below).
Under Settings → Scan Rules you can tune how the scanner reads your folders. Each list adds to the built-in behaviour — you extend the defaults, you can't break them. All three take effect on the next scan.
-
Ignore patterns — folders matching a pattern (and everything inside them)
are skipped. Matching is case-insensitive against a folder's name (
WIP) or its full path (*/_archive/*). Adding a pattern also drops any already-indexed models it now covers on the next scan. -
Tag rules — a keyword→tag pair adds an auto-tag to any model whose name
contains the whole keyword (e.g.
Aztec→civ). They supplement the built-in tag detection and do not change how variants group. -
Parts folder names — exact folder names (e.g.
Sprues,Magnets) treated as parts/structure: never indexed as their own model and never used to group variants, alongside the built-ins (Parts, Base, Supports…).
A safety cap protects against an over-broad ignore pattern: if a single scan would remove more than half your models, the cleanup is skipped and logged.
At the bottom of Settings, under Data Management, you can manage the library database itself. This only ever touches the index — your metadata, tags, favorites, and print queue. Your STL files on disk are never modified.
-
Download Backup — saves a consistent snapshot of your whole library as a
.dbfile (named with a timestamp). Keep this somewhere safe; it's the only way to recover your tags, favorites, and queue if something goes wrong. -
Restore from Backup… — pick a previously downloaded
.dbfile to replace your current library with it. The file is validated first (it must be a real STL Library backup), and an older backup's schema is brought up to date automatically. - Delete All Data — wipes the entire index back to empty. You'd then run a full scan to rebuild it.
Restore and Delete are in a Danger Zone: each overwrites or erases your library and cannot be undone, so they make you type a confirmation phrase first. Download a backup before using either. (Neither can run while a scan is in progress.)
A global NSFW On/Off switch in the top-right of the nav. When off, models flagged NSFW are blurred in the grid and detail view. You can flag/unflag any model from its card or detail header, and filter by NSFW status in the Library.
STL Studio · runs 100% locally · made by Brent the Programmer — Patreon · Buy Me a Coffee