Skip to content

Feature Guide

Jump to bottom
github-actions[bot] edited this page Jul 6, 2026 · 104 revisions

Feature Guide

A tour of every screen and what it does.

Library

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 ≠ tag chip; 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.

Variant grouping

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.

Group variants by character folder (opt-in)

If your library is laid out as {creator}/{character}/… — every variant of a figure living somewhere under one character folder — you can skip the name heuristic entirely. Turn on Group variants by character for a scan root (Settings → Library, next to its layout) and the scanner treats the first folder below the creator as the group: everything beneath it becomes one variant group, regardless of how the sub-folders are named. Off by default; rescan to apply. Manual group overrides still win.

Fixing mis-grouped models

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 Merge into group button in the header (alongside Edit, Find on Web, and Split pack):

  • Click Merge into 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. Confirm an existing group's name to join it. (This only joins an existing group — to build a brand-new group from a single loose model, use drag-to-group or the group view instead.)
  • Once grouped, the button changes to an indigo Group: [name] chip. Click it to merge into a different group, or click ✕ beside it to remove the model from the group.

How grouping durability works

Every manual grouping action — drag-to-group, merge, split, rename, "Merge into group" — writes directly to a durable variant group record, applied immediately (no rescan needed). Because the group is a first-class record rather than a per-model note, a future rescan never undoes it: the scanner's auto-grouping only ever proposes groups for models that aren't already in one.

Removing a model from a group (via Ungroup, × Remove, or clearing Set group) pins it as explicitly ungrouped, sticky across rescans, so the scanner won't just re-propose the same group next time. Explicitly regrouping it (drag, merge, or Set group again) clears that pin.

Model detail

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.

File parts, sup variants & label naming

Each STL file can be labeled with a part type (head, arm, base…) and an editable Name. A part can have multiple sup variants — alternate supported/cut versions of the same part (s1, s2, …) — and the part picker renders one button per sup variant so you can switch which cut you're viewing without hunting through the file list. Selecting a row in the file list and the corresponding button in the part picker stay in sync in both directions, auto-unfolding collapsed sections as needed. Changing a part's category applies to every file linked to it (the base file and all its sups).

The part type field is a combobox: start typing to filter a list of standard suggestions (Body, Head, Arm, Base, Weapon, etc.), or type any custom category name. The dropdown appears automatically and can be dismissed with Escape; pressing Enter or clicking away commits the value.

Settings → Preferences → Horizontal parts layout (on by default) swaps the two-column model detail page for a full-width, scrollable files table below the main grid (with Collections, Location, and Other Files moved into the right column) — handy for models with a lot of parts. The part picker is hidden in this mode since the table serves the same purpose.

Settings → Preferences → Enable part categories turns on the Category field on each file in the model detail view. Files group into collapsible sections and the 3D viewer organises its part picker by category — useful for complex multi-part kits.

3D viewer

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).

Image picker (thumbnails)

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.

Favorites, print queue & printed tracking

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.)

Kit Builder

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.

The Kit Builder uses a two-panel layout:

  • Left panel — the part selector. Files are grouped by label; click a part to toggle it in your selection.
  • Right panel — a live 3D preview pane. Hover any part button to instantly load it in the viewer without affecting your selection. The pane stays pinned to the right side even as you scroll through a long parts list.

To make this useful, label your parts first: on the model detail page, each STL file has a small Label input with common suggestions.

Metadata editing & web enrichment

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).

Triage queue

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

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".

Collections page (/collections)

Each collection card displays its cover image (if set), name, a truncated description (hover for the full text), and model count.

  • Create a collection with the New Collection button.
  • Edit name & description — hover the card and click the pencil icon. The form shows a name field and a scrollable multi-line description box; press Save or click Cancel. Clearing the description removes it.
  • Set a cover image — hover the card and click the image icon. Three options are available in the picker:
    • URL — paste a direct image link. The image is fetched server-side, so CDN hot-link blocking is not an issue.
    • Upload — pick a PNG, JPEG, WebP, or GIF from your computer (max 15 MB).
    • From model — a grid of the collection's models; click any thumbnail to use it as the cover. Use Remove cover at the bottom of the picker to clear a cover that's already set.
  • 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. The cover image file is also deleted.
  • Click a collection card to open its detail view.

Collection 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.

Adding models to a collection

There are two ways:

  1. 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.

  2. 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.

Notes

  • 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.

Bulk editor (tags & enrich)

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 folder

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.

Libraries (the import destination)

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.

The flow

  1. Pick a source folder at /import → Preview packs. This opens the Import Preview screen (/import/preview).
  2. One card per pack — each immediate subfolder of the source is a pack card (files directly in the source form a single pack).
  3. 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.
  4. 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.
  5. 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.

Notes

  • Quick import (whole folder) on /import keeps the original one-shot index of the entire source in a single pass (each immediate subdir = a creator, loose files → an _Inbox creator) — handy when you don't need per-pack review.
  • Inbox flag — un-filed imports are marked inbox; the Library's ?is_inbox=1 filter 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.

Creators & per-creator rescan

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, then fetch each matched product's full detail and bulk-apply the complete metadata set: title, description, tags, category, license, thumbnail, source URL, and external ID. One run enriches every matched model — including all variants in a group — so you no longer have to open each model and run Find on Web by hand. Expand any match (the chevron) to preview the description, tags, category, and license it would apply before committing. MyMiniFactory and Cults3D use their APIs when configured (see Settings → AI & Integrations); Gumroad is scraped. A product whose detail can't be fetched still receives the shallow fields, so nothing is lost.

Paint Shelf (Painting Guides)

The Paint Shelf is always available in the nav — it's standalone paint inventory and doesn't require the guides feature. Enabling Settings → Painting Guides additionally adds the Guides entry (authoring and reading step-by-step painting guides).

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.

PaintRack CSV import & export

The Paint Shelf's import/export uses the CSV format from PaintRack by Courageous Octopus — a great paint-inventory app. STL Studio isn't affiliated with it; we just interoperate with its export so you can reuse a shelf you've already built.

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).

Swatch colors in the CSV

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.

Color-match studio

The Color match button on the Paint Shelf opens a studio that suggests paints from your shelf to match a reference photo (a render, box art, or a painted mini).

  • Value-first. For each sampled color you get a Value ladder — a shadow → mid → highlight ramp in the same hue family, anchored on the sampled mid-tone (Dark Camo Green → Green → Bright Yellow-Green) so the steps read as a cohesive recipe — then a Hue match (opaque paints ranked by ΔE2000), and a labelled Glaze / wash list for transparents. Every suggestion carries a confidence band (very close, confirm, family, loose) — suggestions to confirm by eye, never auto-applied.
  • Eyedropper. Click anywhere on the preview to match that exact spot — sample the skin, then the hair, then the leather, each with its own suggestions. The Palette overview below is an automatic read of the whole image, with the background excluded so the subject leads.
  • Value mode (on by default) greys the swatches so you can read values; turn it off to compare hues in color.
  • Large photos are downscaled in the browser before upload, so even a phone shot uploads instantly.

Painting guides

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 .html file 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.
  • Validation panel + publish gate. While editing, a validation panel lists problems grouped by severity, each linking to the exact step. Blocking issues (a swatch paint you don't own, or a code that fails its line's pattern) must be fixed before you can publish — trying to publish with a blocking issue is rejected. Warnings (an empty tab, a step with no swatches, value numbers that barely differ) are advisory and don't block.
  • Theming. Each guide carries its own colour theme, editable in the guide editor's Theme section: colour pickers for background, surfaces, borders, text and accent, plus a hero-gradient field, with a live mini-preview. Leave a field blank to inherit the default guide theme you set under Settings → Painting Guides → Default guide theme, which every new guide starts from. Themes apply in the in-app reader and the exported PDF; a guide's raw head_style (from imported guides) still wins as an escape hatch.
  • 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 (the export menu, top-right of a guide) renders that same print-styled document to a downloadable PDF. The menu carries per-export reward-stamping options: a Patreon-exclusive footer (on by default), an optional tier label, and a watermark (off by default). If the guide belongs to a series, Export series bundle renders every published guide in that series into one PDF, with an optional cover page. 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.

Reorganize library

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.

Settings

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).

AI & Integrations

Settings → AI & Integrations has three sections.

AI APIs

A list of named AI API connections. Add as many as you need — different models, local Ollama instances, or separate keys for different purposes. Each entry has:

  • Name — a human-readable label used to identify it in the AI Functions selectors below (e.g. "Ollama Local", "Anthropic Creative").
  • Type — Anthropic or OpenAI-compatible (covers Ollama, LM Studio, and any OpenAI-API-compatible endpoint).
  • Model — for Anthropic, a dropdown of supported Claude models; for OpenAI-compatible, the app fetches the available model list from the base URL automatically when you enter it.
  • Effort — (Anthropic only) controls reasoning depth: Low, Medium, or High.
  • Timeout — how long (in seconds) to wait for a response from this endpoint before giving up. Defaults to 10s, which suits a local Ollama. A remote Ollama loading a model for the first time (a "cold start") can take 30–90s or more, so raise this for remote endpoints — e.g. 60. The setting is per-connection, so a fast local API and a slow remote one can each have their own value.
  • API key — stored encrypted server-side, using a separate encryption key (STL_SECRET_KEY, see Docker configuration) so a leaked database alone doesn't expose it. For Ollama and similar local endpoints, a key is optional.

You can add multiple entries of the same type — for example, two Anthropic entries using different models for different tasks, or both a local Ollama instance and a remote OpenAI-compatible endpoint.

AI Functions

Controls which AI features are active and which named API each one uses.

  • AI Guide Drafts — when enabled, an AI generates a first-draft painting guide for review before saving. Choose which configured API to use.
  • AI Naming & Organizing — when enabled, normalizes part names, assigns categories, and links presupported files on a per-model basis. Choose which configured API to use. Internally, fast built-in heuristics run first and handle well-named files on their own — the AI is only called for files the heuristics can't classify. But the review modal only ever shows suggestions the AI actually produced: it's success via the API, or nothing — a heuristic guess is never presented as if the AI made it. If every file was already unambiguous, if the AI call failed, or if no API is configured yet, the modal opens with a clear explanation instead of any rows to review — see Logging to inspect the details of a failed call.

Works with either an OpenAI-compatible API (e.g. Ollama) or an Anthropic connection — assign one under AI APIs, then select it here. If a remote endpoint is slow to respond, raise that connection's Timeout (see AI APIs above).

Metadata

Third-party integrations that enrich your library with creator details, metadata, and thumbnails.

  • Cults3D — connect with a Cults3D username + API key. API access is gated; request it in #api-help on the Cults3D Discord. Credentials are stored encrypted.
  • MyMiniFactory — add a MyMiniFactory API key (register an app under MyMiniFactory Settings → Developer). Stored encrypted.

When configured, these APIs are used automatically during web enrichment.

Logging

Settings → Preferences → Logging sets how much the backend writes to its output. Pick one of the five standard levels — DEBUG, INFO (the default), WARNING, ERROR, CRITICAL. The change takes effect immediately, without a restart, and persists across restarts.

  • INFO — normal operation. Includes a one-line-per-step trace of AI calls (endpoint, model, timeout, elapsed time, HTTP status, outcome).
  • DEBUG — everything in INFO plus verbose detail, including the raw response body returned by the AI endpoint. Useful when diagnosing why an AI call behaves unexpectedly.
  • WARNING and above — quieter; only problems (failed/timed-out AI calls, etc.) are logged.

Viewing the logs depends on how you run the app. Under Docker:

docker compose logs -f backend

The initial level can also be set at startup with the LOG_LEVEL environment variable (see Docker configuration); a value chosen in the UI overrides it and is what survives restarts.

Scan rules

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.

Backup, restore & reset

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 .db file (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 .db file to replace your current library with it. The file is validated first (it must be a real STL Studio 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.)

NSFW toggle

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

STL Studio

Clone this wiki locally