Add local 3D model viewer (three.js + occt-import-js) for STEP/STL, 8px box + caption; embed guide; licenses

2026-08-28 15:24:56 +02:00
parent 11216f8996
commit e13a5433d9
11 changed files with 1752 additions and 1 deletions
@@ -0,0 +1,36 @@
+# Embedding a 3D model (STEP / STL) in a note
+
+The share can render `.step` / `.stp` / `.stl` models interactively (three.js + occt-import-js,
+hosted locally). There are two ways to embed a model, depending on how you store the file.
+
+## Option A – Model as its own note (file note)
+
+1. Create (or upload) a **file note** and make sure its **title ends in `.step`, `.stp` or `.stl`**,
+   e.g. `bracket.step` or `rear_housing.stp`.
+2. Put it under a category in the blog and set `publish=true`.
+3. The note's share page then shows the interactive **3D viewer** automatically:
+   drag to rotate, scroll to zoom; below the model there is a caption with the file name.
+
+## Option B – Model embedded inline in a text note (attachment)
+
+1. Upload the STEP/STL file as an **attachment** of the note:
+   drag & drop it onto the note, or use the attachment dialog (paperclip icon).
+2. **Rename the attachment** so its title ends in `.step`, `.stp` or `.stl`
+   (the viewer detects a model by the file name). Example: `flange.step`.
+3. **Insert the attachment link** into the note body:
+   right-click the attachment → “Insert link”, or drag the attachment into the text.
+   (Trilium creates a link showing the file name.)
+4. On the share, that link is automatically replaced by the embedded 3D viewer.
+
+> Tip: STL (plain triangle meshes) is rendered with three.js only; STEP (CAD B-rep) is
+> parsed by occt-import-js (OpenCASCADE WASM, LGPL-2.1). The first STEP view downloads the
+> ~7.6 MB WASM once and then caches it in the browser.
+
+## Requirements
+
+- The `3d model viewer` script must be wired: `~shareHtml → 3d model viewer`
+  (inheritable) on the blog root, `shareHtmlLocation=body:end`.
+- The five libraries must exist as notes and be referenced by the script via the
+  placeholder tokens in `scripts/3d_model_viewer.js`:
+  `__THREE_ID__`, `__THREE_ORBIT_ID__`, `__THREE_STL_ID__`, `__OCCT_JS_ID__`,
+  `__OCCT_WASM_ID__` (see the README installation for the note titles).