IFC 3D model viewer component for web applications - fully self-contained with local IFCLoader
npm install @sequent-org/ifc-viewerIFC 3D model viewer component for web applications. Основан на Three.js и web-ifc для просмотра BIM моделей в браузере.
✨ Полностью автономный пакет - не требует внешних CSS фреймворков (Tailwind, Bootstrap и т.д.).
Важно про стили: CSS пакета заскоплен под контейнер .ifc-viewer-container, поэтому подключение viewer не влияет на внешний сайт (Bootstrap/глобальные reset'ы не ломаются).
1. Установите пакет:
``bash`
npm install @sequent-org/ifc-viewer
2. Используйте в коде:
`javascript`
import { IfcViewer } from '@sequent-org/ifc-viewer'
const viewer = new IfcViewer({
container: '#viewer-container',
ifcUrl: '/path/to/model.ifc'
})
await viewer.init()
Готово! Пакет полностью автоматический - никаких дополнительных настроек не требуется.
Если нужно подключать стили вручную (например, для SSR/Node, или если вы хотите полностью контролировать загрузку CSS):
`javascript`
import { IfcViewer } from '@sequent-org/ifc-viewer/no-style'
import '@sequent-org/ifc-viewer/src/style.css'
По умолчанию пакет включает пресет "Тест" — это рекомендованные настройки визуала (тени + самозатенение + ACES/sRGB + SSAO + Environment), чтобы модель выглядела корректно сразу после интеграции.
Если нужно отключить и вернуться к базовым настройкам:
`javascript
import { IfcViewer } from '@sequent-org/ifc-viewer'
const viewer = new IfcViewer({
container: '#viewer-container',
ifcUrl: '/path/to/model.ifc',
useTestPreset: false,
})
await viewer.init()
`
`bash`
npm install @sequent-org/ifc-viewer
Никаких дополнительных настроек не требуется! Пакет автоматически:
- ✅ Находит WASM файл из node_modules
- ✅ Применяет патч совместимости Three.js
- ✅ Отключает Web Workers для стабильности
- ✅ Работает в любом проекте "из коробки"
Умный поиск WASM: Пакет автоматически ищет файл по путям:
- /node_modules/web-ifc/web-ifc.wasm (основной путь)/wasm/web-ifc.wasm
- (если скопировали в public/wasm/)/web-ifc.wasm
- (если скопировали в корень public/)
- И другие стандартные пути
Важно: Пакет использует парсинг в главном потоке (Web Workers отключены) для максимальной совместимости с различными окружениями.
`javascript
import { IfcViewer } from '@sequent-org/ifc-viewer'
// Создание просмотрщика с автозагрузкой модели (минимальный режим)
const viewer = new IfcViewer({
container: document.getElementById('viewer-container'),
ifcUrl: '/path/to/model.ifc'
// showSidebar: false (по умолчанию)
// showControls: false (по умолчанию)
// showToolbar: true (по умолчанию)
// wasmUrl: null (автоматически определяет путь к WASM)
})
await viewer.init()
`
`javascript
import { IfcViewer } from '@sequent-org/ifc-viewer'
const viewer = new IfcViewer({
container: document.getElementById('viewer-container'),
ifcUrl: '/models/building.ifc',
wasmUrl: '/custom-path/web-ifc.wasm' // Кастомный путь к WASM файлу
})
await viewer.init()
`
В Laravel проекте с Vite:
`javascript
// В вашем JS файле
import { IfcViewer } from '@sequent-org/ifc-viewer'
function showIfcModal(ifcUrl) {
const modal = document.getElementById('ifc-modal')
const container = modal.querySelector('.modal-content')
const viewer = new IfcViewer({
container: container,
ifcUrl: ifcUrl,
wasmUrl: '/storage/web-ifc.wasm' // Путь к WASM в Laravel storage
// Минимальный режим по умолчанию - только просмотрщик с верхней панелью
})
viewer.init().then(() => {
modal.style.display = 'flex'
})
}
`
Настройка в Laravel:
WASM файл автоматически загружается из node_modules. Дополнительная настройка не требуется!
Для кастомных путей (опционально):
`javascript`
const viewer = new IfcViewer({
container: container,
ifcUrl: ifcUrl,
wasmUrl: '/storage/web-ifc.wasm' // Только если нужен кастомный путь
})
Важно для Laravel: Пакет работает "из коробки" без дополнительных настроек Vite.
- Автономные стили - не требует Tailwind CSS, Bootstrap или других фреймворков
- Умный поиск WASM - автоматический поиск по популярным путям
- Отключенные Web Workers - парсинг в главном потоке для максимальной совместимости
- Fallback защита - автоматическое переключение на резервные пути при ошибках WASM
- Обработка ошибок - graceful degradation при критических ошибках
- Поддержка wasmUrl - гибкая настройка пути к WASM файлу
- Патч совместимости Three.js - автоматическое исправление проблем с mergeGeometries
- IFCWorker - Web Workers отключены для предотвращения проблем интеграции
- Внешние зависимости - все стили и ресурсы включены в пакет
- WASM файл - нужно скопировать из node_modules (один раз)
- Браузеры: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
- Фреймворки: React, Vue, Angular, Laravel, Next.js, Nuxt.js
- Сборщики: Vite, Webpack, Rollup
- Серверы: Node.js, PHP, Python, .NET
`javascript
const viewer = new IfcViewer({
container: '#viewer-container',
autoLoad: false // не загружать автоматически
// По умолчанию только верхняя панель, загрузка через кнопку "📁 Загрузить"
})
await viewer.init()
// Альтернативно: программная загрузка файла
const fileInput = document.getElementById('file-input')
fileInput.addEventListener('change', async (e) => {
const file = e.target.files[0]
if (file) {
await viewer.loadModel(file)
}
})
`
`javascript
const viewer = new IfcViewer({
container: '#viewer-container',
ifcUrl: '/models/building.ifc',
wasmUrl: '/custom-path/web-ifc.wasm' // Указываем свой путь к WASM
})
await viewer.init()
`
| Опция | Тип | По умолчанию | Описание |
|-------|-----|--------------|----------|
| container | HTMLElement \| string | обязательно | DOM элемент или селектор для контейнера |ifcUrl
| | string | null | URL для загрузки IFC файла |ifcFile
| | File | null | File объект для загрузки |wasmUrl
| | string | null | URL для загрузки WASM файла web-ifc |showSidebar
| | boolean | false | Показывать боковую панель с деревом |showControls
| | boolean | false | Показывать нижние кнопки управления |showToolbar
| | boolean | true | Показывать верхнюю панель инструментов |autoLoad
| | boolean | true | Автоматически загружать при инициализации |theme
| | string | 'light' | Тема интерфейса ('light' \| 'dark') |
#### wasmUrl - Настройка пути к WASM файлу
Параметр wasmUrl позволяет указать кастомный путь к WASM файлу библиотеки web-ifc. Это особенно полезно при интеграции пакета в проекты с нестандартной структурой ресурсов.
Особенности:
- По умолчанию: Если не указан, используется автоматически определяемый путь из папки public/wasm/https://example.com/web-ifc.wasm
- Поддержка форматов: Полные URL () и относительные пути (/assets/web-ifc.wasm)
- Обратная совместимость: При ошибке загрузки кастомного пути автоматически переключается на дефолтный
- Обработка ошибок: В консоль выводится предупреждение при неудачной настройке кастомного пути
Примеры использования:
`javascript
// Относительный путь
const viewer1 = new IfcViewer({
container: '#viewer',
wasmUrl: '/assets/web-ifc.wasm'
})
// Полный URL
const viewer2 = new IfcViewer({
container: '#viewer',
wasmUrl: 'https://cdn.example.com/web-ifc.wasm'
})
// Путь с подпапкой
const viewer3 = new IfcViewer({
container: '#viewer',
wasmUrl: '/static/libs/web-ifc.wasm'
})
`
Когда использовать:
- При размещении WASM файла в нестандартной папке
- При использовании CDN для статических ресурсов
- При интеграции в фреймворки с особой структурой ресурсов (Laravel, Next.js и т.д.)
`javascript
// Инициализация просмотрщика
await viewer.init()
// Загрузка модели
await viewer.loadModel('/path/to/model.ifc') // по URL
await viewer.loadModel(fileObject) // File объект
// Быстрая повторная загрузка (персистентный кэш GLB в IndexedDB)
await viewer.loadModelWithCache('/path/to/model.ifc')
// Явное управление кэшем
await viewer.saveModelToCache(viewer.getViewer().activeModel, { cacheKey: 'my-model' })
await viewer.clearModelCache({ cacheKey: 'my-model' })
// Управление интерфейсом
viewer.setSidebarVisible(true)
viewer.setTheme('dark')
// Получение информации
const modelInfo = viewer.getModelInfo()
const threeViewer = viewer.getViewer()
const ifcService = viewer.getIfcService()
// Освобождение ресурсов
viewer.dispose()
`
Пакет поддерживает сохранение последней модели в GLB и хранение её в IndexedDB.
При повторном открытии модель загружается значительно быстрее, чем исходный IFC.
`javascript
import { IfcViewer } from '@sequent-org/ifc-viewer'
const viewer = new IfcViewer({ container: '#viewer', autoLoad: false })
await viewer.init()
// Первый запуск: загрузит IFC и сохранит GLB в IndexedDB
await viewer.loadModelWithCache('/models/building.ifc')
// Повторный запуск: возьмёт GLB из кэша
await viewer.loadModelWithCache('/models/building.ifc')
`
Публичные методы кэша:
- loadModelWithCache(url, { cacheKey?, autoSave? })saveModelToCache(object3D, { cacheKey?, metadata? })
- clearModelCache({ cacheKey?, url? })
-
Примечания:
- IndexedDB доступен только в браузере.
- Кэш работает между перезагрузками страницы.
- Ключ по умолчанию строится из URL.
Просмотрщик отправляет пользовательские события:
`javascript
const container = document.getElementById('viewer-container')
// Готовность к работе
container.addEventListener('ifcviewer:ready', (e) => {
console.log('Просмотрщик готов', e.detail.viewer)
})
// Модель загружена
container.addEventListener('ifcviewer:model-loaded', (e) => {
console.log('Модель загружена', e.detail.model)
})
// Ошибка
container.addEventListener('ifcviewer:error', (e) => {
console.error('Ошибка просмотрщика', e.detail.error)
})
// Освобождение ресурсов
container.addEventListener('ifcviewer:disposed', (e) => {
console.log('Ресурсы освобождены')
})
`
Стили подключаются автоматически при импорте пакета и полностью автономны - не требуют Tailwind CSS, Bootstrap или других внешних фреймворков.
Если нужно подключить стили отдельно:
`javascript`
import '@sequent-org/ifc-viewer/style.css'
Преимущества локальных стилей:
- ✅ Полная автономность пакета
- ✅ Нет конфликтов с CSS фреймворками сайта
- ✅ Меньший размер bundle'а
- ✅ Быстрая загрузка без внешних зависимостей
При включенной опции showToolbar доступны следующие инструменты:
Для локального тестирования пакета:
`bash`
git clone
cd ifc-viewer
npm install
npm run test:manual
Откроется страница test.html с интерактивными тестами.
- .ifc - стандартные IFC файлы.ifs
- - вариант IFC (если используется в вашем пайплайне).ifczip
- - архивы IFC.zip
- - ZIP архивы с IFC файлами.fbx
- - FBX модели (базовая поддержка).glb
- - glTF Binary (рекомендуется для загрузки из файла).gltf
- - glTF JSON (часто требует внешние .bin/текстуры; надёжнее грузить по URL).obj
- - Wavefront OBJ (можно загружать один OBJ или OBJ+MTL(+текстуры) через мультивыбор файлов).3ds
- - 3D Studio (3DS) (рекомендуется загружать .3ds + текстуры через мультивыбор файлов).3dm
- - Rhino 3D (3DM) (требуются rhino3dm.js/rhino3dm.wasm, пакет копирует их в /public/wasm/rhino3dm/ автоматически).stl
- - STL (ASCII/Binary). Обычно без материалов/цветов — отображается с дефолтным материалом..dae
- - COLLADA (DAE) (можно загружать .dae + текстуры через мультивыбор файлов)
Добавление новых форматов делается через реестр загрузчиков (ModelLoaderRegistry): регистрируете новый XxxModelLoader, и UI/точки входа загрузки остаются без изменений.
Ошибка загрузки WASM:
``
Failed to load web-ifc.wasm
Решения:
1. Проверьте путь к файлу:
`javascript`
// Убедитесь, что файл доступен по указанному пути
const viewer = new IfcViewer({
container: '#viewer',
wasmUrl: '/correct-path/web-ifc.wasm'
})
2. Проверьте CORS настройки:
- Для локальной разработки используйте относительные пути
- Для продакшена настройте CORS для WASM файлов
3. Проверьте MIME-тип:
`nginx`
# В nginx.conf
location ~* \.wasm$ {
add_header Content-Type application/wasm;
}
4. Альтернативные пути:
`javascript`
// Попробуйте разные варианты
wasmUrl: '/web-ifc.wasm' // корень
wasmUrl: '/assets/web-ifc.wasm' // папка assets
wasmUrl: '/static/web-ifc.wasm' // папка static
Отладка:
- Откройте DevTools → Network и проверьте загрузку WASM файла
- Проверьте консоль на предупреждения о wasmUrlweb-ifc.wasm
- Убедитесь, что файл существует и доступен
Ошибка IFCWorker:
``
Failed to load IFCWorker.js
Решение: Эта ошибка не должна возникать, так как Web Workers отключены в пакете. Если она появляется:
1. Проверьте версию пакета:
`bash`
npm list @sequent-org/ifc-viewer
Ошибка mergeGeometries:
``
mergeGeometries is not a function
Решение: Пакет автоматически применяет патч совместимости для Three.js 0.149+. Если проблемы продолжаются:
1. Проверьте версию Three.js:
`bash`
npm list three
2. Убедитесь, что используется Three.js 0.149+:
`bash`
npm install three@^0.149.0
2. Очистите кэш:
`bash`
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
3. Проверьте консоль браузера - должно быть сообщение "Web Workers отключены"
Ошибка при импорте:
``
Cannot resolve module '@sequent-org/ifc-viewer'
Решения:
1. Убедитесь в правильной установке:
`bash`
npm install @sequent-org/ifc-viewer
2. Проверьте package.json:
`json`
{
"dependencies": {
"@sequent-org/ifc-viewer": "^1.0.1"
}
}
3. Для TypeScript проектов:
`typescript`
import { IfcViewer } from '@sequent-org/ifc-viewer'
- Node.js >= 16
- Современный браузер с поддержкой WebGL и WebAssembly
- Для работы требуются файлы web-ifc.wasm в публичной папке проекта
- Поддержка ES6 модулей в браузере
- IfcViewer - основной класс-обертка для интеграции
- IfcService - сервис загрузки и парсинга IFC файлов
- Viewer - Three.js сцена и рендеринг
- IfcTreeView - компонент дерева IFC структуры
- Web Workers отключены - парсинг в главном потоке
- IFCWorker исключен - предотвращает проблемы интеграции
- Fallback защита - множественные пути к WASM файлу
- Автономные стили - встроенные CSS без внешних зависимостей
При помощи с интеграцией пакета учитывайте:
1. WASM файл автоматически найден - никаких дополнительных настроек не требуется
2. Web Workers отключены - не пытайтесь их включить
3. Используйте параметр wasmUrl только для кастомных путей к WASM файлу
4. Пакет полностью автономен - не требует внешних CSS фреймворков
5. Поддерживает все современные фреймворки - React, Vue, Angular, Laravel
6. Работает "из коробки" - просто установите и используйте
- Проверьте консоль на сообщение "Web Workers отключены"
- WASM файл автоматически загружается из node_modules
- Используйте DevTools → Network для проверки загрузки ресурсов
- При проблемах используйте параметр wasmUrl` для кастомного пути
MIT License
Для вопросов и предложений создавайте Issues в репозитории проекта.