@skarmind/stl-viewer

English consumer guides: AGENTS.md | llms.txt

Изолированная framework-agnostic npm-библиотека для просмотра 3D STL-моделей в браузере.

• ✅ TypeScript-first API
• ✅ Three.js рендеринг
• ✅ Загрузка STL из URL, File, Blob, ArrayBuffer
• ✅ Auto-fit модели к viewport (fitRatio)
• ✅ OrbitControls (rotate/zoom/pan)
• ✅ Fullscreen mode (API + опциональная кнопка UI)
• ✅ Авто-обработка resize (window + ResizeObserver)
• ✅ Опциональный встроенный UI (fullscreen/reset/clear)
• ✅ Полный cleanup через dispose()
• ✅ События и callbacks

Установка

npm install @skarmind/stl-viewer three

three является peer dependency.

Быстрый старт

import { ModelViewer } from '@skarmind/stl-viewer';

const container = document.getElementById('viewer') as HTMLElement;

const viewer = new ModelViewer(container, {
  fitRatio: 0.75,
  backgroundColor: '#121212',
  ui: { enabled: true },
});

await viewer.loadFromUrl('/models/test-cube.stl');

Публичный API

Конструктор

new ModelViewer(container: HTMLElement, options?: ViewerOptions)

Методы загрузки

• load(input: ModelLoadInput): Promise<ModelLoadedEvent>
• loadFromUrl(url: string): Promise<ModelLoadedEvent>
• loadFromFile(file: File): Promise<ModelLoadedEvent>
• loadFromBlob(blob: Blob, fileName?: string): Promise<ModelLoadedEvent>
• loadFromArrayBuffer(data: ArrayBuffer, options?): Promise<ModelLoadedEvent>

Управление сценой

• clear(): void
• resetView(): void
• fitModelToView(): void
• setFitRatio(ratio: number): void
• setBackground(color: string | number): void
• setWireframe(enabled: boolean): void
• setGridVisible(visible: boolean): void
• setAxesVisible(visible: boolean): void
• setAutoRotate(enabled: boolean): void

Fullscreen

• enterFullscreen(): Promise<void>
• exitFullscreen(): Promise<void>
• toggleFullscreen(): Promise<void>
• isFullscreen(): boolean

Resize и lifecycle

• resize(): void
• dispose(): void

События

• on(event, handler): () => void
• off(event, handler): void

Поддерживаемые события:

• loadstart
• loadsuccess
• loaderror
• clear
• resize
• fullscreenchange
• dispose

Опции ViewerOptions

interface ViewerOptions {
  antialias?: boolean;
  alpha?: boolean;
  fitRatio?: number; // default: 0.75
  backgroundColor?: string | number; // default: '#121212'
  autoRotate?: boolean;
  wireframe?: boolean;
  showGrid?: boolean;
  showAxes?: boolean;
  ui?: ViewerUIOptions;

  onLoadStart?: () => void;
  onLoadSuccess?: (event: ModelLoadedEvent) => void;
  onLoadError?: (event: ViewerErrorEvent) => void;
  onClear?: () => void;
  onResize?: (event: ViewerResizeEvent) => void;
  onFullscreenChange?: (event: FullscreenChangeEvent) => void;
  onDispose?: () => void;
}

Встроенный UI

UI полностью опционален и рендерится только внутри контейнера viewer. Он не добавляет глобальные CSS и не влияет на layout внешнего приложения.

ui: {
  enabled: true,
  showFullscreenButton: true,
  showResetButton: true,
  showClearButton: true,
}

Архитектура и расширяемость

Библиотека построена с учетом будущей поддержки OBJ/PLY/GLTF:

• ModelLoaderAdapter — контракт загрузчика формата
• LoaderRegistry — реестр адаптеров
• STLModelLoader — текущая реализация для STL

Для нового формата достаточно добавить новый adapter и зарегистрировать его в реестре.

Локальная разработка

npm install
npm run dev

Скрипты

• npm run dev — demo (Vite dev server)
• npm run build — полный build: lint + typecheck + generate test STL + library + demo
• npm run build:lib — сборка библиотеки
• npm run build:demo — сборка demo
• npm run preview — предпросмотр demo
• npm run lint — ESLint
• npm run typecheck — TypeScript check
• npm run gen:test-model — генерация тестовой STL модели

Демо

Demo находится в examples/ и включает:

• загрузку STL из файла
• загрузку STL по URL
• reset/fullscreen/clear
• настройки background/wireframe/grid/axes/autoRotate/fitRatio
• статусный блок loading/loaded/error
• примеры вызова API

Тестовая модель: public/models/test-cube.stl

Десктопное приложение

Помимо библиотеки, доступно полноценное десктопное приложение STL Viewer на базе Next.js + Tauri.

• 🖥️ Запуск без браузера — нативное окно
• ⚡ Весь функционал конфигуратора в offline-режиме
• 🔄 Автообновление через GitHub Releases

Скачать

Последнюю версию можно скачать в разделе GitHub Releases:

• Windows — .msi или .exe
• macOS — .dmg (Apple Silicon / Intel)
• Linux — .AppImage

Запуск из исходников

cd stl_viewer_configurator
npm install
npm run tauri:dev

Сборка

cd stl_viewer_configurator
npm run tauri:build

Лицензия

MIT