Introduction¶

When using language models to handle mechanical or structural problems, a common obstacle is the model file itself. Formats such as OBJ, STL, and STEP are either pure geometric data or BREP solids that require a CAD kernel to discretize. A pure language LLM usually receives only a stream of bytes that it cannot understand. In the past, the approach was either to run a local CAD toolchain and excerpt the results, or simply to give up.

dsh-3d-model-viewer is a plugin in the DeepSeek Harness (DSH) ecosystem. Its approach is to split the task into two steps: first, render the model directly in a Web interface for humans to see; then, translate the same model into standardized, LLM-readable JSON and pass it to the language model. Below we introduce its positioning, installation, and usage.

What This Is¶

• Project: lishLRF/dsh-3d-model-viewer, author lishLRF, MIT license.
• Positioning: View OBJ/STL/STEP 3D models in the DSH Web interface and translate the model into standard JSON (format identifier dsh-3d-model/v1), allowing a language model to understand a part without a CAD kernel.
• Supported formats: OBJ, STL, STEP (.step / .stp).

It conforms to DSH’s “everything is a plugin” structure. A single package contains two sides:

• Host side: Registers the read_3d_model tool, allowing the Agent to read OBJ/STL files from disk by itself and translate them into standard JSON. It also exports the translation library (translateFromBytes / translateObj / translateStl and the schema).
• Client side: A browser bundle built according to the DSH client-module contract. It registers a floating panel in shell.overlay, renders with three.js, and reaches the conversation through the sessions scope.

Core Features¶

1. Display the model in the floating panel on the right side of the DSH Web interface, with styling aligned to the DSH theme. Supported interactions include rotation, panning, and zooming, along with adjustable material (color, metalness, roughness, wireframe), lighting (ambient light + key light), and a cross-section (clipping plane) view.

2. Translate supported models into the unified dsh-3d-model/v1 JSON, including semantic analysis: surface area, volume, watertight status, shape classification, and a natural-language description (analysis.naturalDescription). The translated result looks roughly like this:

{
  "schema": "dsh-3d-model/v1",
  "meta": { "sourceFormat": "stl", "name": "bracket.stl", "units": "mm" },
  "bounds": { "min": [0,0,0], "max": [40,20,10] },
  "summary": { "partCount": 1, "triangleCount": 1024 },
  "analysis": {
    "totalSurfaceArea": 2200.0,
    "totalVolume": 8000.0,
    "watertight": true,
    "naturalDescription": "bracket.stl: 1 part (box), ..."
  },
  "parts": [ { "id": "part-0", "vertices": [ "..." ], "indices": [ "..." ] } ]
}

3. Send to AI: One-click writes the JSON + prompt into the DSH input box and uploads it together with the user input. It can also be sent immediately as a queued message. The JSON can also be downloaded or copied.

4. Agent side: The read_3d_model tool registered on the Host side covers OBJ/STL. The Agent can call it on a specific file path and receive the standard JSON.

STEP files are discretized and parsed by the browser-side occt-import-js (an OpenCascade WASM port). This is supported only by the Web viewer. When the Host-side read_3d_model tool encounters a STEP file, it indicates that the file must be opened in the Web viewer.

Installation and Enabling¶

Environment requirements: Node ≥ 20, pnpm ≥ 10. It is recommended to install with a precompiled Release tgz in one step:

dsh plugin --profile web add https://github.com/lishLRF/dsh-3d-model-viewer/releases/download/v0.1.1/dsh-3d-model-viewer-0.1.1.tgz

The precompiled package already includes the build artifacts, so no build-script authorization is required after installation.

Then start the Web interface:

dsh web        # 等价于 dsh --profile web

There are three ways to verify that it is active:

1. A “3D Model Viewer” panel appears in the upper-right corner of the Web interface.
2. Have the Agent call read_3d_model on a specific .obj / .stl path. It should return standard JSON, indicating that the Host tool is registered.
3. You can also check the combined result without starting it:

dsh --profile web --dump-config

Finding the # == dsh-3d-model-viewer section in the output means success.

Uninstall command:

dsh plugin --profile web remove dsh-3d-model-viewer

If installing from GitHub source (dsh plugin --profile web add github:lishLRF/dsh-3d-model-viewer), note two points: pnpm ≥ 10 refuses to run prepare build scripts for git dependencies, so you need to write allowBuilds: dsh-3d-model-viewer: true into the profile’s pnpm-workspace.yaml and then re-run add. Because prepare runs scripts on your machine, it is recommended to pin the commit in the form github:lishLRF/dsh-3d-model-viewer#<sha>.

Typical Usage¶

1. Open a session and click “Load Model” in the “3D Model Viewer” panel, or drag and drop files directly (.obj .stl .step .stp).
2. Rotate, pan, and zoom to inspect the model; adjust material and lighting; enable the cross-section view when needed.
3. (Optional) Write model notes in the “Model Description” textbox. These notes are written into meta.description of the standard JSON and are provided to the LLM together with “Send to AI,” reducing misinterpretation.
4. Click “Send to AI” to append the JSON + prompt to the input box, or choose “Send immediately.” You can also “Download JSON” / “Copy JSON” to export the document.

For quick verification, the project includes three sample models. You can load them directly in the panel:

The panel toggle can be controlled on the configuration page under “Settings → Plugins.” The selection is persisted in the browser. headless/TUI profiles can still use the read_3d_model tool, except there is no viewer panel.

Use Cases and Cautions¶

Best for developers building agents on DSH whose workflows involve parts or 3D model files. The goal is to let a human see the model first, then have the Agent discuss or reason based on geometric information such as dimensions, volume, and whether the shape is closed.

Before using it, there are several points to know:

• Environment requirements are Node ≥ 20 and pnpm ≥ 10; panel features depend on the web profile.
• The STEP WASM binary is loaded by default from a fixed CDN and cannot be deployed from the same path as the packaged client.js. Offline deployment requires modifying STEP_WASM_URL in src/client/load.ts (or hosting the .wasm file beside the bundle) and then rebuilding.
• Material files (mtllib) are only parsed on a best-effort basis for names and colors; full MTL texture/BRDF loading is not within v1 scope.
• For units, OBJ/STL default to unknown (the formats themselves do not include units), while STEP reads unit information when present. The model is not auto-centered, and source coordinates are preserved.

In addition, the plugin runs with the permissions of the current dsh process, and read_3d_model can read file paths on disk that you specify. Before installing any third-party plugin, it is recommended to check its source code and license. This project is MIT-licensed, but occt-import-js wraps OpenCascade (LGPL-2.1 + exception). The OCCT WASM binary is independently dynamically loaded. See the repository’s LICENSE and THIRD_PARTY_NOTICES.md for details.

Conclusion¶

dsh-3d-model-viewer solves a very concrete problem: it allows users to see OBJ/STL/STEP models directly in the DSH Web interface, while translating the same geometry into standard JSON such as dsh-3d-model/v1. This lets a language model obtain useful information such as dimensions, volume, and shape classification without relying on a CAD kernel. If 3D model files frequently appear in your agent workflow, it is worth trying.

• Community catalog page: https://www.skillhub.cn/plugins/lishLRF/dsh-3d-model-viewer
• GitHub repository: https://github.com/lishLRF/dsh-3d-model-viewer

(The community catalog is an independent site and has no official affiliation with DeepSeek / Huanfang.)