Skip to content

Render STL thumbnails with a small CPU companion - #118

Closed
k-kostin wants to merge 2 commits into
omacom:thumbnail-rowsfrom
k-kostin:codex/native-stl-thumbnails
Closed

k-kostin wants to merge 2 commits into
omacom:thumbnail-rowsfrom
k-kostin:codex/native-stl-thumbnails

Conversation

@k-kostin

@k-kostin k-kostin commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

STL thumbnails currently require an installed 3D thumbnailer. Add a small CPU companion built with Folio's existing C++/Qt dependencies, so ordinary STL files can get a transparent thumbnail without starting F3D or a graphics context.

explicit user thumbnailer
  otherwise: bundled CPU STL helper
    if absent or declined: selected system thumbnailer

The helper runs outside the UI process. It reads a bounded snapshot, scans it twice without allocating a vertex graph, renders both sides with a depth buffer and 2×2 coverage samples, and declines malformed, colored or excessive geometry. CPU and system attempts share one deadline and existing process-session cleanup. Native failure identity includes helper availability/version, fallback and output bucket. Successful pictures use the existing shared cache.

Thanks to @thisisgm for the Flea renderer this camera, raster math and palette were adapted from. Its MIT notice is included.

Draft, stacked on #67 (7cbd76c6); rebase and repeat checks after that lands. This does not include the separate cancellation changes in #117. A local combined build passed the cancellation regressions, including the native STL route. Packaging companion: omacom/omarchy-pkgs#2704. Packagers must ship the companion and its additional license beside Folio; the pending install rules in #107 should include them when rebased.

Evidence

  • Before: thumbnailsDrawStlWithoutAnExternalRenderer fails on the base with no external STL renderer.
    After: the real companion generates and caches the synthetic tetrahedron.
  • Final bin/test: 220 Folio checks + 8 renderer checks passed, using isolated Qt image plugins matching the CI package set (the desktop also has KDE RAW plugins). Release build passed on x86_64.
  • Renderer tests also passed under ASan/UBSan. A separate fixed-seed 4,000-input parser/raster exercise found no sanitizer errors. Checks cover binary/ASCII equivalence, winding/depth, premultiplied transparency, extreme coordinates, malformed input, output preservation and FIFO refusal.
  • Provider tests cover user overrides, missing/broken helper, missing/invalid PNG, system fallback, failure-cache changes, one shared timeout and large-thumbnail refusal followed by a successful smaller request.

Local QML grid comparison: eight generated, non-personal STL fixtures, 12–960,000 triangles (largest 45.8 MiB), ten alternating pairs after warm-up. Empty application thumbnail cache, warm OS page cache; Ryzen 7 9700X, Qt 6.12, F3D 3.5 native plugin. Offscreen Qt Quick software backend; these are local measurements, not physical-screen frame latency or CI timings.

Metric System F3D Bundled CPU
First ready thumbnail, median / p95 562 / 605 ms 55 / 61 ms
All eight ready, median / p95 1004 / 1042 ms 139 / 150 ms
Whole-scope CPU time, median 3332 ms 276 ms
Whole-scope peak memory, median 880 MiB 123 MiB

Timing runs used the renderer commit 28bffb2; the final d87b9dd adds only bucket-aware failure identity and its regression. No user model or derived image is included.

Merge Danger

Door: two-way. Removing the companion restores the existing system-thumbnailer route.

Blast Radius: thumbnails. STL gets a new default monochrome renderer; explicit user overrides and colored-model fallback remain. Input is capped at 128 MiB / two million triangles, output at 1024 px, and raster work at 128 million bounding-box samples. No new runtime package or Rust toolchain is needed. aarch64 has not been built locally.

@omarchybot

Copy link
Copy Markdown
Contributor

Closing this draft, @k-kostin, on the maintainer's decision not to have Folio ship its own STL renderer — thank you for it, and for the benchmark, which is what settled the question.

The line it crosses is Folio becoming the author of a renderer for one file format: about 800 lines, a second binary with its own license, a parser for untrusted input, and a packaging change coordinated with omarchy-pkgs. STL thumbnails stay with an installed thumbnailer instead: Arch's f3d ships f3d-plugin-native.thumbnailer, which your own benchmark ran through Folio's thumbnailer path, so STL can get thumbnails by installing it, and the details pane can say so once #66's missing-package hints land.

Reviewed by reading the change against main and #66/#67, which it is stacked on; second opinion from Codex at medium effort and muse-wonder at high. Your other thumbnail work (#117, #120) is unaffected and is being worked toward merging.

@omarchybot omarchybot closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants