feat: add STL thumbnail preview support

[ludvig-sandh]

Summary

Adds thumbnail preview support for .stl files, rendering the mesh offscreen via open3d.
(as per request #351)

There was already a stubbed-out _model_stl_thumb method with a commented-out matplotlib-based approach that had been abandoned because "it did not play nice with multithreading."
I hit the same problem with open3d, described below, and worked around it differently.

The multithreading problem

TagStudio renders thumbnails from a pool of os.cpu_count() worker threads.
open3d's offscreen renderer (built on Google's Filament engine) is not thread safe.
Calling it from two threads at the same time crashes the entire process with a native PreconditionPanic ("This thread has not been adopted") that Python's exception handling cannot catch.
Sequential use from different threads works fine, only true concurrent use triggers the crash.

I fixed it by serializing all STL rendering behind a single lock, so only one thread ever renders an STL mesh at a time, regardless of which worker thread picks up the job.

Also, a very large or maliciously crafted STL file could take a long time to parse and render, and because rendering is now sequential, one slow file would block every other STL thumbnail in the library from rendering while it's being processed.
To mitigate this problem, I added an STL file size cap of 256MB and a max triangle count of 5M.

Evidence of the cap working: a 260MB file is not previewed (as expected):

Perhaps sequential rendering is a deal breaker but perhaps this can serve as a basis to continue working on. Or it's low priority enough to work until a better solution is found.

Tasks Completed

• New dependency: open3d~=0.19. (I believe this pulls in a lot of transitive dependencies and may increase the program size quite a bit. Just good to know)
• Manually verified by running the app against a test library containing STL files. Thumbnails render correctly.

• Platforms Tested:
  • Windows x86 (will test)
  • Windows ARM
  • macOS x86
  • macOS ARM (will test)
  • Linux x86
  • Linux ARM
• Tested For:
  • Basic functionality
  • PyInstaller executable

[CyanVoxel]

Crashed with a SIGTRAP on macOS 15.7.7 during the item rendering phase of startup, and on second launch and onward I get these RuntimeErrors for all my STL files:

2026-07-04 12:44:22 [error    ] Couldn't render thumbnail      error=RuntimeError filepath=PosixPath('/Users/cyanvoxel/Local/Projects/TagStudio Project/Test Libraries/Example/3D Models/STL Dump/brick_2x4_3001_resized_1.02.stl')

Also I suggest reading the current #1231 discussion on 3D modeling rendering if you haven't already

[ludvig-sandh]

I see. Crashed on Windows too. Let's keep this as a draft for now and I will rethink how to solve this the best way.

Thanks for linking that discussion. Missed that one.

Now leaning towards a custom solution. STL files are apparently pretty simple and rigid, so should be simple enough and cross-platform by nature. The only issue is performance, which is something you discussed. But we may not need GPU acceleration (at least for now). For small preview renders we can probably get away with CPU renders. Especially if we leverage Numpy + multithreading. If we can get down to <50ms per preview then GPU wouldn't even be that much better.

I will try it out and see if it can both look good and be efficient enough for previews.

[Computerdores]

To mitigate this problem, I added an STL file size cap of 256MB and a max triangle count of 5M.

Would be good to have both of those configurable for users with systems that are significantly better or worse than the average