3D Embed Plugin - How to use

Currently supported filetypes: stl, glb, obj (and mtl), fbx, 3mf

This plugin allows you to showcase all sorts of 3D models in your vault and notes using the infamous three.js library. As opposed to other plugins this plugin allows you to embed your 3D models locally. This means you won't have to upload your models to some other website and embed that in your note, but rather just have the file in your vault and the plugin does all the other work for you.

This plugin also allows you to make your scene with the whole model look as nice as possible. Influencing a lot of variables such as background colors, autorotation, lighting, scales, etc. [Look at the documentation below for all the options]

[!Note] Developer Note!: If the plugin misses anything, feel free to open a github issue or tag me in the obsidian discord preferably in this thread @jesse5. I am very open to suggestions and bugfixes and love hearing them :)

[!Tip] If you like my plugin feel free to leave a star on my repository (it's like a reward)

Table of Contents

• 1. IMPORTANT!: Showing all filetypes in obsidian
• 2. Watch this video that showcases how to use the plugin
• 3. Two ways to view a 3D model
  • 3A. Embed a 3D model in a note
    • 3A.1 Alternatively — embed a grid of models
  • 3B. Open a 3D file directly from the file tree
• Opening 3D models in notes (codeblock)
• Minimal Configuration
• Additional Configuration
  • Model settings
  • Render block settings
  • Grid Settings
  • Generic Scene Settings
    • Advanced Scene setting - HDR/HDRI loading
  • STL Configurations
  • OBJ information
  • Lighting Configuration
  • Camera configuration
  • GUI (BETA)
• Standard Settings
• Bases — Snapshot & Card View
  • Taking a snapshot
  • Bases settings
  • Setting up a Base card view
• Precautions
• Future plans
• Support
• FAQ

1. IMPORTANT!: Showing all filetypes in obsidian:

Go to the settings tab of obsidian -> 'Files and Links' -> toggle the 'Show all file types' This allows you to see every type of file in your obsidian vault, including 3D model files such as stl.

2. Watch this video that showcases how to use the plugin:

https://github.com/user-attachments/assets/9b10c36c-36c3-4bc1-a4a7-f5d00f735ec7

3. Two ways to view a 3D model

There are two distinct ways to view a 3D model with this plugin:

	Method	Best for
A	Embed in a note — insert an interactive 3D scene directly inside a markdown note, alongside your text, images, and other content	Documenting, annotating, or presenting models in context
B	Open directly — left-click a 3D file in the file explorer and it opens in its own dedicated tab, just like an image or PDF	Quickly inspecting a model without opening or editing any note

---

3A. Embed a 3D model in a note

1. Drag Model from file overview/manager into note as an embed	2. position cursor on line with 3D model embed OR select the line with the embed (You can select multiple models to include multiple in one scene)

3. On line with embed execute the embed 3D command (ctrl+p) -> Embed 3D: Single Scene: Add a 3D embed at cursor position	4. Voila a 3D model

3A.1 Alternatively — embed a grid of models

Version 1.1.0 also allows you to include grids of 3D models in your vault if you wanna showcase multiple models or perspectives at once

Video of getting a grid	possible view of a grid

To get the grid, similarly to the instructions above, drag in all the models you want. Select all the models with a drag selection, and execute the grid command: (ctrl+p) -> Embed 3D: Grid: Add a 3D grid embed from selection.

---

3B. Open a 3D file directly from the file tree

Version 1.1.4 adds a dedicated viewer tab. Simply left-click any supported 3D file in the file explorer and it opens in its own tab — no note required.

[!Note] Make sure "Show all file types" is enabled in Settings → Files and Links (see step 1 above), otherwise 3D files won't be visible in the file tree.

The viewer uses all your global plugin settings (background color, lighting, camera position, scale, etc.)

---

Opening 3D models in notes

If you embed in a note; Each embed will contain a codeblock of information. You can access this by clicking in the top right of the scene OR by moving your type cursor into the codeblock

where to click to get to the codeblock	view of a codeblock

This codeblock will allow you to modify A LOT of settings for this block only. If you want settings to be generally applied to all scenes you embed you should go to the settings tab.

Minimal Configuration

A codeblock should minimally contain these values per scene:

"models": [
   {"name": "Airship.glb", "scale": 0.7, "position": [0, 0, 0], "rotation": [0, 0, 0]}
],
"camera": {
   "orthographic": false,
   "camPosXYZ": [0,5,10], "LookatXYZ": [0,0,0]
},
"lights": [
   {"type": "directional", "color": "FFFFFF", "pos": [5,10,5], "target": [0,0,0], "strength": 1, "show": false},
   {"type": "ambient", "color": "FFFFFF", "pos": [0,0,0], "strength": 0.5, "show": false}
]

[!Important] The last line of the codeblock should not end on a comma, all other lines should (The codeblock uses JSON structure)

Or in case of a grid:

```3D-grid
"gridSettings": {},
"cell1": {}, //...standard minimum config. See above codeblock
"cell2": {}
```

But this is just the tip of the iceberg! The codeblock can receive a lot more variables to modify the scene and give you more control.

Additional Configuration

Look at the codeblock to alter minor things in the scene. It shows all the config options of a 3D scene for now.

Beside the basic configuration, these are lines you can add for more control:

Model settings

This will come preloaded when entering the command, but this config allows you to change elements about the model(s). You can add multiple models in this array to render multiple models in one scene at the same time.

"models": [
   {"name": "Airship.glb", "scale": 0.7, "position": [0, 0, 0], "rotation": [0, 0, 0]}
],

• name is the name of the file of the 3D model in your vault
• scale is the scale of the object related to your export size
• position allows you to change the position of the model in the scene
• rotation allows you to change the rotation of the model in the scene

Render block settings

To change the width or height, or the css alignment of a block:

"renderBlock": {
   "widthPercentage": 100,
   "height": 300,
   "alignment": "center"
}

• widthPercentage goes from 1 - 100
• height is in pixels
• alignment has 3 options (begin, center, end)

Grid Settings

When using a grid, instead of using Render Block Settings you can use the config below:

"gridSettings": {
   "columns": 4,
   "rowHeight": 200,
   "gapX": 10,
   "gapY": 10
},

• columns states how many columns your grid has
• rowHeight can either be a number, or a string "auto". Auto makes an automatic square, while a number dictates the height of one row in pixels
• gapX and gapY dictate the gapsize between scenes in your grid in pixels

Generic Scene Settings

To change some other scene settings:

"scene": {
   "showGuiOverlay": false,
   "autoRotation": [0, 0, 0],
   "backgroundColor": "4bb8dd",
   "showGroundShadows": true,
   "orbitControlDamping": true,
   "showAxisHelper": false, "length": 5,
   "showGridHelper": false, "gridSize": 10
},

• showGuiOverlay provides you with a gui (see further down)
• autoRotation rotates your model automatically on any axis
• backgroundColor can also be set to transparent or any hexvalue for a color.
• showGroundShadows places a plane in the scene with a shadow material (Transparent but shows shadows)
• orbitControlDamping can be toggled for smoother orbit controls
• showAxisHelper and showGridHelper show scene helpers such as a grid or the main axis.

Advanced Scene setting - HDR/HDRI loading:

If you want to utilize HDR loading in your scenes, for very realistic lighting and reflections you can do so. It is important to mention that this will cause your vault, or specifically note, to load more slowly since it has to load the HDR image, which can be quite big in size.

You can add this inside the scene tag as seen above:

"hdriBackground": {
   "texturePath": "filename.hdr",
   "sceneBackground": true,
   "baseGeometry": true
}

• texturePath is the filename of the HDRI. (You dont have to include the vault path, filename suffices)
• sceneBackground puts the HDR texture you provide as the scene background
• baseGeometry loads a torus with very metallic material so you can see how well your HDRI works

Example of HDRI with a base Geometry:

STL Configurations

Specifically for stl model files, I added some additional configuration

"stl": {
   "stlColorHexString": "ff0000",
   "stlWireframe":false
},

• stlColorHexString allows you to set the color of an stl model itself
• stlWireframe allows you to show the stl as a wireframe

OBJ information

It's usefull to know that the plugin supports obj models, and thereby the accomponying .mtl files. For them to work, the mtl file has to have the exact same name as the obj file (most 3D programs export them with the same name by default) and they need to be in the same folder.

Lighting Configuration

Lighting settings such as type, color, position, strength and whether you can see a sphere at the location of the light

"lights": [
   {"type": "directional", "color": "FFFFFF", "pos": [5,10,5], "target": [0,0,0], "strength": 1, "castShadows": true, "show": false},
   {"type": "ambient", "color": "FFFFFF", "pos": [0,0,0], "strength": 0.5, "show": false},
   {"type": "attachToCam", "color": "ffffff", "pos": [5,10,5], "strength": 1, "show": false},
   {"type": "point", "color": "ffffff", "pos": [5,10,5], "strength": 1, "castShadows": true, "show": false},
   {"type": "spot", "color": "ffffff", "pos": [5,10,5], "target": [0,0,0], "distance": 0, "angle": 0, "strength": 1, "castShadows": true, "show": false},
   {"type": "hemisphere", "skyColor": "ffffff", "groundColor": "FFFFFF", "strength": 1, "show": false}
],

• type has 6 options directional, ambient, attachToCam, point, spot, hemisphere (each of them can be found in the three.js documentation if you want to read more. Except for attachToCam which just attaches a lightsource to the camera)
• color allows you to set a hexvalue for the color of the light
• position allows you to set the position of the lightsource
• strength allows you to set the strength of the lightsource
• show allows you to physically see the lightsource position by placing a sphere at the position coordinates you provide (can be usefull for setting up your scene)
• castShadows only available in the directional, point and spot lightsource, which enables the lightsource to cast shadows
• target only available in the directional and spot lightsource, to aim it at a point
• distance only available in the spot lightsource, allows you to say how far the light projects
• angle only available in the spot lightsource, allows you to adjust the angle of the spotlight
• skycolor and groundColor are part of the hemisphere lightsource, for a color transition. (look at three.js documentation for more details)

Camera configuration

To change camera settings:

"camera": {
   "orthographic": false,
   "camPosXYZ": [0,5,10], "LookatXYZ": [0,0,0]
},

• orthographic allows you to switch between a perspective and orthographic camera
• camPosXYZ allows you to set the camera position
• LookatXYZ allows you to aim the camera at a specific point

GUI (BETA)

Now working with a codeblock might be a tad annoying to finetune your models. So I've been working on a GUI that allows you to change some of the parameters with more ease. By changing this option in your config of the scene to true

"scene": {
   "showGuiOverlay": false | true,
},

You can use transform controls and color pickers to finetune your scene a bit better. See the images below, you have a color picker (becomes unavailable when your background color is set to transparent), a rotation tool, a position tool and moving the camera. When clicking the checkmark, the scene will be saved as is in the config. But you can also reset it if you mess up somehow.

Standard Settings

Use the settings tab, to alter standard settings for how all the models are initially loaded. The settings tab has the same options as the codeblock above, but are global settings, the codeblock for each model will override the global setting if they are different. But the codeblocks initial values will be filled according to the global settings. Such as background color, size of 3D embed, or scale of the model.

Bases — Snapshot & Card View

Obsidian's Bases feature lets you build database-like views of your notes. In card view, each note can display a cover image sourced from a frontmatter property. The 3D Embed plugin can generate snapshot images of your 3D scenes and automatically write them as a property on your note, so your models show up as preview thumbnails in any Base card view.

Taking a snapshot

Every 3D embed has a small camera icon in its overlay alongside the existing copy and trash buttons. Clicking it captures the current frame of the scene and saves it as a .png file in your vault.

The filename follows the pattern:

3D-Embed-thumbnail-{modelname}-{timestamp}.png

And will be saved in the folder you specify in the settings or in the root of your vault if nothing is specified

Bases settings

These options are found under the Bases header in the plugin settings tab (All the way at the bottom).

Setting	Description
Snapshot folder	Vault folder where snapshot images are saved. Leave empty to save to the vault root. Example: attachments/3d-snapshots
Auto-write snapshot property	When enabled, saving a snapshot automatically adds a 3D Embed-thumbnail property to the note containing the embed.
Overwrite existing snapshot	When enabled, the previous snapshot referenced by the 3D Embed-thumbnail property is deleted from the vault before the new one is saved. Useful for keeping your vault tidy when you frequently re-export a scene. Note: this permanently deletes the old file, only use it if you do not need a history of snapshots.

Setting up a Base card view

1. Generate a snapshot for each note you want to appear with a preview. Click the camera icon on the 3D embed — if Auto-write snapshot property is on, the 3D Embed-thumbnail property is written to the note's frontmatter automatically. If the toggle is off, add the property manually: open the note's properties panel and create a property named 3D Embed-thumbnail with a wikilink to your snapshot image.
2. Create a Base. Open any folder in Obsidian and switch to the Bases view, or create a new .base file. Filter or sort the notes containing 3D embeds as needed.
3. Switch to card view using the view selector in the Base toolbar.
4. Set the image property. In the Base view settings (the gear or configure icon), find the Image property option and set it to 3D Embed-thumbnail. Obsidian will now display the snapshot as the card's cover image.
5. Filter the results. Be sure to add a filter where file has property 3D Embed-thumbnail to only show the relevant files.

Each time you adjust a scene and want to refresh the thumbnail, click the camera icon again. With Overwrite existing snapshot enabled, the old image is removed and replaced automatically.

---

Precautions:

1. The plugin uses three.js, thereby the amount of active renderers (webGL contexts) is limited to 16. This means that you can either have 16 single scenes shown at once, or 16 grids at the same time (grids only use one renderer if the advanced scissor option is togled on). a. It seems that on mobile scissoring is not possible, and the amount of active renderers is limited to 8 at once.
2. Big models will be laggy (defined by vertex count), since obsidian has a limited amount of RAM that cannot be altered. If you have a big model in a note, and that note is open, your whole vault may lag. Be aware of this. Most light models cause no issue.
3. If your model is not showing up in the scene, half of the time the scale of the model is the cause, so try playing around with sizes both large and small.

Future plans:

1. Be able to run custom three.js script for a scene.
2. Camera Path Animations
3. More intuitive GUI for editing scenes (Modal)

Support:

If you are enjoying 3D embed, then feel free to support my work and enthusiasm by buying me a coffee on: Buy me a coffee

FAQ

• My plugin on mobile doesnt want to update in version? Or it updates, but when restarting the app, it reverts to an older version.
  • Delete and reinstall the plugin, i have no idea what could be the cause of this, but this seems to solve the issue. it will sadly reset your plugin settings but all your note embeds will remain intact :)
• I have both an .obj file and .mtl file, but my textures dont not show up?
  • Check if your .obj and .mtl file have the exact same name
• I have both an .obj file and .mtl file, but my model doesnt show up
  • This has to do with the .mtl file, obj's come with different export settings for the mtl file, sometimes the mtl file in itself refers to external files, such as modelname-Alpha.png or modelname-RGBA.png, if you have these files move them to the same folder as the mtl file. Otherwise, attempt to re export your obj with different mtl settings. And lastly if you dont really care about the textures, remove the mtl file, and your model will load without textures.
• Where can I request new features?
  • In a GitHub issue or tag me in the obsidian discord @jesse5
• Where can I report bugs?
  • In a GitHub issue or tag me in the obsidian discord @jesse5
• I want to export my note as a pdf, but the 3D scenes arent there.
  • If you use the better Export pdf community plugin you can export your markdown notes with a nice snapshot of your 3D scenes!