Scanning and Folder Structure

Scanning & Folder Structure

This explains how STL Studio reads your library — useful if your models are laid out unusually or aren't being detected the way you'd expect.

• The folder layout it expects
• Custom folder layouts
• How a "model" is detected
• STL file part names
• Thumbnails
• Automatic tagging
• needs_review
• Full scan vs. per-creator rescan
• Incremental scanning

---

The folder layout it expects

The scanner is built around this general shape, but it's flexible about depth:

<scan root>/
  <Creator>/                         ← top-level folder = a creator
    <Character or Product>/          ← a grouping folder (optional)
      Images/  Renders/  …           ← preview images (any common name)
      <Variant>/                     ← e.g. "Bust", "1:6 Pre-supported"  ← a MODEL
        head.stl  body.stl  base.stl
      <Another Variant>/             ← a separate MODEL

Key ideas:

• By default, the top-level folder under a scan root is a creator — never a model itself, even if its name contains a word like "Figures" or "Miniatures." If your creators live deeper (e.g. under a genre folder), set a custom layout per scan root.
• A model is a folder containing the actual printable parts for one product or variant. A folder is only ever indexed as a model if its subtree contains 3D files (.stl / .3mf / .obj) — render/preview-only folders are skipped. A .3mf counts toward that check but isn't indexed as a printable part itself — it lands in Other Files instead, since it's commonly a slicer project bundling multiple parts rather than one printable piece. Slicer project and slice files (.lys, .chitubox, .ctb, .photon, .pw0/.pwx/.pws, .fhd) are never indexed, and any indexed by older versions are cleaned up after the next full scan.
• Folders below a model (e.g. head/, base/, Supported/STL/) are treated as parts of that model, not separate models.

Custom folder layouts

If your library doesn't put creators at the top level, you can tell each scan root how its folders are arranged with a layout template (Settings → the Layout field on each scan location). A template describes the levels above your models, one per /, down to the level that names the creator:

Token	Meaning
{creator}	This level's folder name is the creator. Required, and must be the last token.
{tag}	This level's folder name is added as an auto-tag to every model beneath it (e.g. a genre or collection folder).
{ignore} (or *)	A structural level that's walked past and carries no meaning.

Everything below the creator level is still detected automatically (the character/variant/model heuristics below), so you only describe the part of the tree above your products.

Examples:

Template	Disk layout	Result
{creator} (default)	Abe3D/…	Top folders are creators — today's behavior.
{tag}/{creator}	Sci-Fi/Abe3D/…	Creators sit under a genre folder; every model gets a sci-fi tag.
{tag}/{tag}/{creator}	Sci-Fi/Mechs/Abe3D/…	Two tag levels — models tagged sci-fi and mechs.
{ignore}/{creator}	_incoming/Abe3D/…	A wrapper folder is skipped; creators sit one level down.

The same creator can appear under more than one {tag} branch — its models are merged under one creator, each keeping the tag from its own path. Changing a layout takes effect on the next scan (full or per-creator).

Not the same thing as the destination template. Settings shows these two near each other and they point opposite ways. A scan root's Layout (above) says how your existing folders are read. The destination template says where models should live — it drives Reorganize, new creator folders, and the "unorganized" badge. Changing one does not change the other.

Both now live on the same card: Layout reads, Destination writes. A location's Destination is optional and empty means inherit — first the library-wide template under Settings → Library → Destination Layout, then the built-in default. See Per-scan-root destination templates.

How a "model" is detected

For each folder (that contains 3D files somewhere in its subtree), the scanner decides "is this a model?" in priority order:

1. Name signals — the folder name contains scale/type/modifier hints (e.g. 1:6, Bust, Pre-supported), marking a product boundary.
2. Parts pattern — the folder has STLs and its sub-folders look like parts (head, base, supported…).
3. Deepest fallback — the folder has STLs and nothing below it has STLs.

If none match, the scanner recurses deeper, carrying the deepest meaningful (non-structural) folder name along as character context, which powers variant grouping.

Structural folders — support status (Supported/Unsupported/Presupported), mesh-repair state (Original/Repaired), containers/formats (STL, Lychee, and slicer folders like LYS, CTB, Chitu), pre-slice prep (Sliced/Presliced), render folders (Renders, Images, img), pure scale/cut descriptors, and base folders that spell out their sizes and shapes (Bases 25mm-32mm (Round+Square)) — are never used as the character. Otherwise every creator's LYS (or STL, Supported, …) folder would collapse into one giant cross-character variant group.

A folder holding no 3D files anywhere beneath it does not influence grouping at all, whatever it is called. When sibling folders are compared to work out which product they belong to, only folders that actually contain models get a say — so a gallery folder named img Barbarella, mulan renders, final or just 1 cannot split a character into separate products by being counted as one. This is a content rule rather than a naming rule precisely because such folders are named inconsistently. The one exception protects you from a surprise: if the mesh-free folder's name agrees with what the real folders already say, the grouping it was already producing is kept rather than changed.

The real character is inherited from the nearest meaningful ancestor instead, so Spiderman/Supported/LYS/ groups under Spiderman. A meaningful folder does not take over the character either, when its own name merely extends the one it inherited — 2B holding 1_4 2B YoRHa - Abe3D is one more level of the same product, so everything below stays 2B rather than splitting off under the longer name. Only a genuinely different name starts a new character, which is why Orc holding a Goblin Warrior still gives you a Goblin Warrior. A model left with a stale structural name by an older scan (e.g. a folder that used to be called LYS) self-heals to the derived character name on the next rescan. A model's name is owned by the scanner and re-derived on every scan, so improvements to the naming rules always reach models that were indexed by an earlier version. (Your own edits live on the title field, which the scanner never touches.)

When naming such a folder, the nearest owning ancestor takes precedence over the carried character, and a folder sitting directly under the creator counts as a product by its position even when every word in it looks structural — so RPG Bases/RPG Bases Supported is named RPG Bases, not after whichever release the scanner happened to walk just before it. Pure container levels (Models, Files, STL) are stepped over when looking for that owner.

If the resulting name still has no identity of its own — a bare parts word like Bases — it is qualified by the release or product that owns it, so …/52 - OCTOBER 2024 REANIMATION/Models/05 - Bases Supported becomes October 2024 Reanimation Bases rather than colliding with every other Bases folder in the library.

When the heuristic gets it wrong, you can fix it by merging the model into a group — the correction is a durable group membership, so future rescans leave it alone instead of re-deriving it from the heuristic.

Models versus release packages

A scanned model is a catalog/viewer unit; a release package is a physical move boundary. One package may contain several models, such as printable files at its root plus a separately indexed Alternate/ subtree. With Preserve release package structure enabled under Settings → Library → Library Tools, Reorganize finds the physical character ancestor and treats its next child as the package root. It then moves that complete subtree while keeping all relative folders and companion files unchanged. A model stored directly in the character directory uses that directory as its package boundary. If the stored character cannot be matched to an ancestor folder, Reorganize blocks the package for review rather than flattening it. See Reorganize Library.

Folders and files beside those package roots form the character envelope. This commonly includes shared img/, Images/, or Renders/ folders, but unrecognized loose companion files are protected the same way. Reorganize moves the envelope only when every package under the character is selected. With a partial selection it remains at the original character path, and the preview explicitly reports that it will be retained.

STL file part names

Each STL file's Name (part_name, shown in the model detail file list) is auto-derived from its filename the first time the scanner indexes it — underscores/hyphens become spaces, each word is title-cased, and a Sup_-prefixed or -supported-suffixed file gets a leading "Supported ". This happens for both a regular library scan and an imported folder — both go through the same indexer. It's a one-time default: once set, a rescan never overwrites it, so a manual rename or an AI Organize suggestion always sticks.

Thumbnails

For each model the scanner looks for a preview image, walking upward from the model folder toward the creator folder. It prefers images in folders named like Renders, Images, Photos, Preview, Gallery, etc., then any loose image, then any image in a non-model sub-folder. This is why a shared Renders/ folder at the character level still gives each variant a thumbnail.

If the thumbnail it picks is wrong, override it with the image picker.

Automatic tagging

From folder and file names, the scanner auto-detects and tags:

• Scale — ratio scales like 1:6, 1:9, 1:12 (including glued forms like 1_12scale), and miniature heights like 28mm, 75mm.
• Type — bust, statue, figure, diorama, chibi, miniature, terrain, and more.
• Modifiers — pre-supported, uncut, NSFW, pin-up, etc.

A ratio in a file name only counts as a scale when it leads the name (1_6 base.stl), or when its denominator is a real print scale and the folder is not numbering its parts. Otherwise it is treated as a part index (base_1-2, base_cut1-3) and ignored, so a model cut into numbered pieces no longer picks up a scale tag for every piece. Ratios in folder names are always read as scales.

Collector-scale ratios (1:4 through 1:12) also auto-add the statue tag, since figures at those scales are statues by convention.

These appear as auto-tags on the model and feed the Library's tag filter. Auto-tags are kept separate from tags you add yourself, and a rescan refreshes them — so as detection improves, your tags improve too.

Scan rules

The built-in detection above can be extended under Settings → Scan Rules. Every rule list adds to the defaults (it never replaces them) and applies on the next scan. See Scan rules for the full description:

• Ignore patterns — skip folders by name (WIP) or path glob (*/_archive/*). One pattern is built in and always applied: __MACOSX, the sidecar folder macOS adds to every zip it creates. It mirrors the real folder tree and fills it with placeholder files, so without this the scanner indexes a duplicate, unprintable copy of everything in the archive. If you have scanned Mac-authored zips before, expect those duplicates to disappear on your next full scan.
• Tag rules — add an auto-tag when a name contains a keyword (Aztec → civ).
• Parts folder names — extra exact folder names treated as parts/structure.

needs_review

When a newly-indexed model ends up with a name that carries no identity of its own — a bare Bases, STL or RPG Bases — the scanner flags it needs_review so you can confirm or fix it in the Triage queue.

The question is asked after every naming rule above has run, so it only fires on the folders that all of them failed to name. A product folder whose meshes sit in a STL or Supported STL subfolder is an ordinary layout and is never flagged; on a well-organised library the queue is close to empty.

The queue is durable. A model is flagged only when it is first indexed, which means an item you haven't reviewed survives every rescan, and one you dismiss never comes back. The number flagged during a given run is reported separately in the scan status as flagged_for_review — see checking the scanner found everything.

Full scan vs. per-creator rescan

• Full scan (Scan Library button) walks every scan root and every creator. Use it for the first scan, or after adding lots of new creators.
• Per-creator rescan (Rescan button on the Creators page) re-walks just one creator's folder. Since you usually add models one creator at a time, this is the fast way to pick up new additions without re-scanning your whole library.

Only one scan runs at a time — starting one while another is running is blocked.

A full scan also cleans up file records left behind by a rename done outside the app (e.g. a bulk lowercase/hyphenate pass run directly on disk): any STL file record whose path no longer resolves, in a model folder that's otherwise still present, is removed. Without this, Reorganize would keep reporting that model as having "missing files" indefinitely — the old record never goes away on its own, since indexing only ever adds newly found files, it doesn't remove ones whose path changed. A per-creator rescan doesn't need this: it already fully reindexes that creator's files from scratch every time.

Incremental scanning

A full scan is incremental: folders whose modification time hasn't changed since the last scan skip the expensive file-indexing step. Metadata and tags are still refreshed every scan, so improvements to tag detection (like new scale rules) are picked up even on unchanged folders.

A per-creator rescan always does a full reindex of that creator, so it's the reliable way to force everything for one creator to be re-read.

Libraries (import destinations)

A library is a scan root you've given a name and marked as a writable import destination. It's the folder the Import flow files packs into.

Configure one in Settings, on a folder's card:

• Library — a display name (e.g. minis). Shown in the import screen's destination dropdown; defaults to the folder's basename if left blank.
• Import destination — tick this to mark the folder writable as a move target. Only ticked folders appear in the import dropdown. Untouched folders remain index-only (scanned in place, never moved into).

If the destination drive isn't a scan root yet, add it first under Settings → Add a Folder, then name it and tick Import destination.

Marking a folder an import destination only makes it eligible. The actual on-disk move still requires the Reorganize Library feature flag (reorganize_enabled) to be turned on under Settings → Library → Library Tools — it defaults off, and while off both Reorganize and import moves are refused. This mirrors Reorganize's safety posture.

That flag gates writes, not the layout itself.

An import move does not follow your destination template. It always lands in {creator}/{title} under the chosen destination library — a fixed shape, so an import is predictable regardless of how the rest of your library is filed. What it does share with the destination template are the two slugify toggles under Settings → Library → Destination Layout, which is why an import arrives already lowercase-and-hyphenated when that setting is on. Run Reorganize afterwards to file imported models under the template for the root they landed in.