@sequent-org/ifc-viewer 1.2.4-ci.61.0 → 1.2.4-ci.63.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sequent-org/ifc-viewer",
   "private": false,
-  "version": "1.2.4-ci.61.0",
+  "version": "1.2.4-ci.63.0",
   "type": "module",
   "description": "IFC 3D model viewer component for web applications - fully self-contained with local IFCLoader",
   "main": "src/index.js",

package/src/IfcViewer.js

@@ -41,6 +41,7 @@ export class IfcViewer {
    * @param {boolean} [options.showSidebar=false] - Показывать ли боковую панель с деревом
    * @param {boolean} [options.showControls=false] - Показывать ли панель управления (нижние кнопки)
    * @param {boolean} [options.showToolbar=true] - Показывать ли верхнюю панель инструментов
+   * @param {boolean} [options.labelEditingEnabled=true] - Разрешить ли редактирование меток
    * @param {boolean} [options.autoLoad=true] - Автоматически загружать модель при инициализации (modelUrl/modelFile/ifcUrl/ifcFile)
    * @param {string} [options.theme='light'] - Тема интерфейса ('light' | 'dark')
    * @param {Object} [options.viewerOptions] - Дополнительные опции для Viewer
@@ -74,6 +75,7 @@ export class IfcViewer {
       showSidebar: options.showSidebar === true, // по умолчанию false
       showControls: options.showControls === true, // по умолчанию false
       showToolbar: options.showToolbar !== false, // по умолчанию true
+      labelEditingEnabled: options.labelEditingEnabled !== false,
       autoLoad: options.autoLoad !== false,
       theme: options.theme || 'light',
       viewerOptions: options.viewerOptions || {}
@@ -389,6 +391,24 @@ export class IfcViewer {
     this.labelPlacement.selectLabel(id);
   }
 
+  /**
+   * Включает/выключает режим редактирования меток.
+   * @param {boolean} enabled
+   */
+  setLabelEditingEnabled(enabled) {
+    if (!this.labelPlacement) return;
+    this.labelPlacement.setEditingEnabled(enabled);
+  }
+
+  /**
+   * Возвращает текущий режим редактирования меток.
+   * @returns {boolean}
+   */
+  getLabelEditingEnabled() {
+    if (!this.labelPlacement) return false;
+    return this.labelPlacement.getEditingEnabled();
+  }
+
   /**
    * @deprecated используйте setLabelMarkers
    */
@@ -564,7 +584,12 @@ export class IfcViewer {
     // В пакете включаем UI "меток" по умолчанию:
     // кнопка "+ Добавить метку" + режим постановки меток + сохранение/восстановление состояния.
     try {
-      this.labelPlacement = new LabelPlacementController({ viewer: this.viewer, container: this.elements.viewerContainer, logger: console });
+      this.labelPlacement = new LabelPlacementController({
+        viewer: this.viewer,
+        container: this.elements.viewerContainer,
+        logger: console,
+        editingEnabled: this.options.labelEditingEnabled,
+      });
       this.cardPlacement = this.labelPlacement;
     } catch (e) {
       console.warn('IfcViewer: LabelPlacementController init failed', e);

package/src/main.js

@@ -54,6 +54,16 @@ if (app) {
   // Остальные контролы (тени/солнце/материалы/визуал/цветокор) будем добавлять пошагово позже.
   // (Старый код управления панелью закомментирован ниже для последующего восстановления при необходимости.)
 
+  // Анимация (damping)
+  const dampingDynamic = document.getElementById("dampingDynamic");
+  const dampingDynamicValue = document.getElementById("dampingDynamicValue");
+  const dampingBase = document.getElementById("dampingBase");
+  const dampingBaseValue = document.getElementById("dampingBaseValue");
+  const dampingSettle = document.getElementById("dampingSettle");
+  const dampingSettleValue = document.getElementById("dampingSettleValue");
+  const dampingSettleMs = document.getElementById("dampingSettleMs");
+  const dampingSettleMsValue = document.getElementById("dampingSettleMsValue");
+
   const testPresetToggle = document.getElementById("testPresetToggle");
   // Шаг 1 (Tone mapping): в текущей версии он входит в пресет "Тест", но exposure можно подстроить.
   const step1ToneToggle = document.getElementById("step1ToneToggle");
@@ -78,6 +88,59 @@ if (app) {
   const step4SaturationValue = document.getElementById("step4SaturationValue");
   const step4Dump = document.getElementById("step4Dump");
 
+  const applyDampingDynamic = (v) => {
+    const on = Number(v) >= 1;
+    if (dampingDynamicValue) dampingDynamicValue.textContent = on ? "1" : "0";
+    try { viewer.setDampingConfig?.({ dynamic: on }); } catch (_) {}
+  };
+  const applyDampingBase = (v) => {
+    const value = Number(v);
+    if (!Number.isFinite(value)) return;
+    if (dampingBaseValue) dampingBaseValue.textContent = value.toFixed(2);
+    try { viewer.setDampingConfig?.({ base: value }); } catch (_) {}
+  };
+  const applyDampingSettle = (v) => {
+    const value = Number(v);
+    if (!Number.isFinite(value)) return;
+    if (dampingSettleValue) dampingSettleValue.textContent = value.toFixed(2);
+    try { viewer.setDampingConfig?.({ settle: value }); } catch (_) {}
+  };
+  const applyDampingSettleMs = (v) => {
+    const value = Math.max(0, Math.round(Number(v)));
+    if (!Number.isFinite(value)) return;
+    if (dampingSettleMsValue) dampingSettleMsValue.textContent = String(value);
+    try { viewer.setDampingConfig?.({ settleMs: value }); } catch (_) {}
+  };
+
+  // Инициализация damping UI от текущих параметров viewer
+  const initDampingUi = () => {
+    const cfg = viewer.getDampingConfig?.() || {};
+    if (dampingDynamic) {
+      dampingDynamic.value = cfg.dynamic ? "1" : "0";
+      applyDampingDynamic(dampingDynamic.value);
+      dampingDynamic.addEventListener("input", (e) => applyDampingDynamic(e.target.value));
+    }
+    if (dampingBase) {
+      const v = Number.isFinite(cfg.base) ? cfg.base : Number(dampingBase.value);
+      dampingBase.value = Number.isFinite(v) ? String(v) : "0.50";
+      applyDampingBase(dampingBase.value);
+      dampingBase.addEventListener("input", (e) => applyDampingBase(e.target.value));
+    }
+    if (dampingSettle) {
+      const v = Number.isFinite(cfg.settle) ? cfg.settle : Number(dampingSettle.value);
+      dampingSettle.value = Number.isFinite(v) ? String(v) : "0.00";
+      applyDampingSettle(dampingSettle.value);
+      dampingSettle.addEventListener("input", (e) => applyDampingSettle(e.target.value));
+    }
+    if (dampingSettleMs) {
+      const v = Number.isFinite(cfg.settleMs) ? cfg.settleMs : Number(dampingSettleMs.value);
+      dampingSettleMs.value = Number.isFinite(v) ? String(v) : "0";
+      applyDampingSettleMs(dampingSettleMs.value);
+      dampingSettleMs.addEventListener("input", (e) => applyDampingSettleMs(e.target.value));
+    }
+  };
+  initDampingUi();
+
   const setStep1UiEnabled = (enabled) => {
     const on = !!enabled;
     if (step1ToneToggle) step1ToneToggle.checked = on;

package/src/styles-local.css

@@ -182,6 +182,7 @@
   display: block;
   transform: translate(-50%, -50%);
   will-change: transform;
+  transition: opacity 160ms ease;
 }
 
 .ifc-label-ghost,
@@ -223,6 +224,12 @@
   cursor: pointer;
 }
 
+.ifc-label-marker--hidden,
+.ifc-card-marker--hidden {
+  opacity: 0;
+  pointer-events: none;
+}
+
 /* Клик ловим на контейнере метки, дочерние элементы пусть не перехватывают */
 .ifc-label-marker .ifc-label-dot,
 .ifc-label-marker .ifc-label-num,

package/src/ui/LabelPlacementController.js

@@ -13,6 +13,8 @@ class LabelMarker {
     this.localPoint = deps.localPoint;
     this.el = deps.el;
     this.sceneState = deps.sceneState || null;
+    this.visible = null;
+    this.hiddenReason = null;
   }
 }
 
@@ -34,6 +36,8 @@ export class LabelPlacementController {
     this.viewer = deps.viewer;
     this.container = deps.container;
     this.logger = deps.logger || null;
+    this._visibilityLogEnabled = !!deps.visibilityLogEnabled;
+    this._editingEnabled = deps?.editingEnabled !== false;
 
     this._placing = false;
     this._nextId = 1;
@@ -46,6 +50,8 @@ export class LabelPlacementController {
     this._ndc = new THREE.Vector2();
     this._tmpV = new THREE.Vector3();
     this._tmpLocal = new THREE.Vector3();
+    this._tmpV2 = new THREE.Vector3();
+    this._tmpNdc = new THREE.Vector3();
 
     this._lastPointer = { x: 0, y: 0 };
     this._ghostPos = { x: 0, y: 0 };
@@ -97,8 +103,22 @@ export class LabelPlacementController {
       v2: new THREE.Vector3(),
     };
 
+    this._autoHide = {
+      active: false,
+      prevHidden: false,
+    };
+    this._showAfterStop = {
+      raf: 0,
+      active: false,
+      lastChangeTs: 0,
+      idleMs: 0,
+      eps: 5e-4,
+      lastCamMatrix: new Float32Array(16),
+    };
+
     this._ui = this.#createUi();
     this.#attachUi();
+    this.#syncEditingUi();
     this.#bindEvents();
     this.#startRaf();
   }
@@ -140,6 +160,14 @@ export class LabelPlacementController {
     try { dom?.removeEventListener("contextmenu", this._onCanvasContextMenu, { capture: true }); } catch (_) {
       try { dom?.removeEventListener("contextmenu", this._onCanvasContextMenu); } catch (_) {}
     }
+    try {
+      const controls = this.viewer?.controls;
+      if (controls && typeof controls.removeEventListener === "function") {
+        try { controls.removeEventListener("start", this._onControlsStart); } catch (_) {}
+        try { controls.removeEventListener("end", this._onControlsEnd); } catch (_) {}
+      }
+    } catch (_) {}
+    try { this.#cancelShowAfterStop(); } catch (_) {}
 
     if (this._raf) cancelAnimationFrame(this._raf);
     this._raf = 0;
@@ -155,7 +183,7 @@ export class LabelPlacementController {
   }
 
   startPlacement() {
-    if (this._placing || this._labelsHidden) return;
+    if (!this._editingEnabled || this._placing || this._labelsHidden) return;
     this._placing = true;
 
     const controls = this.viewer?.controls;
@@ -710,6 +738,7 @@ export class LabelPlacementController {
       try { e.preventDefault(); } catch (_) {}
       try { e.stopPropagation(); } catch (_) {}
       try { e.stopImmediatePropagation?.(); } catch (_) {}
+      if (!this._editingEnabled) return;
       this.startPlacement();
     };
     this._ui.btn.addEventListener("click", this._onBtnClick, { passive: false });
@@ -755,6 +784,7 @@ export class LabelPlacementController {
       const target = e.target;
       const action = target?.getAttribute?.("data-action");
       if (action !== "add") return;
+      if (!this._editingEnabled) return;
       if (this._labelsHidden) return;
       try { e.preventDefault(); } catch (_) {}
       try { e.stopPropagation(); } catch (_) {}
@@ -770,6 +800,7 @@ export class LabelPlacementController {
         if (e.key === "Escape") this.cancelPlacement();
         return;
       }
+      if (!this._editingEnabled) return;
 
       const target = e.target;
       const tag = (target && target.tagName) ? String(target.tagName).toLowerCase() : "";
@@ -904,6 +935,7 @@ export class LabelPlacementController {
 
     this._onCanvasContextMenu = (e) => {
       // Контекстное меню добавления метки по ПКМ на модели (если нет метки под курсором).
+      if (!this._editingEnabled) return;
       try { e.preventDefault(); } catch (_) {}
       try { e.stopPropagation(); } catch (_) {}
       try { e.stopImmediatePropagation?.(); } catch (_) {}
@@ -920,6 +952,19 @@ export class LabelPlacementController {
       this.#openCanvasMenu(hit, e.clientX, e.clientY);
     };
     dom.addEventListener("contextmenu", this._onCanvasContextMenu, { capture: true, passive: false });
+
+    const controls = this.viewer?.controls;
+    if (controls && typeof controls.addEventListener === "function") {
+      this._onControlsStart = () => {
+        this.#beginAutoHideForControls();
+      };
+      this._onControlsEnd = () => {
+        this.#scheduleShowAfterStop();
+      };
+      try { controls.addEventListener("start", this._onControlsStart); } catch (_) {}
+      try { controls.addEventListener("end", this._onControlsEnd); } catch (_) {}
+    }
+
   }
 
   #setGhostVisible(visible) {
@@ -1108,6 +1153,7 @@ export class LabelPlacementController {
     let best = null;
     for (const h of hits) {
       if (!h || !h.point) continue;
+      if (this.#isPointClippedBySection(h.point)) continue;
       const obj = h.object;
       if (obj && obj.isMesh) { best = h; break; }
     }
@@ -1203,6 +1249,7 @@ export class LabelPlacementController {
   }
 
   #emitLabelAction(action, marker = null) {
+    if (!this._editingEnabled) return;
     const target = marker || this.#getSelectedMarker();
     if (!target) return;
     const detail = this.#buildActionPayload(target);
@@ -1211,6 +1258,7 @@ export class LabelPlacementController {
   }
 
   #openContextMenu(marker, clientX, clientY) {
+    if (!this._editingEnabled) return;
     const menu = this._ui?.menu;
     if (!menu || !marker) return;
 
@@ -1324,6 +1372,11 @@ export class LabelPlacementController {
       // если были в режиме постановки — выходим
       try { this.cancelPlacement(); } catch (_) {}
 
+      if (!this._editingEnabled) {
+        this.#handleMarkerClick(marker);
+        return;
+      }
+
       if (e.button === 0) {
         this.#closeContextMenu();
         this.#setSelectedMarker(marker);
@@ -1355,6 +1408,7 @@ export class LabelPlacementController {
     try { marker.el.addEventListener("dragend", onMarkerDragEnd); } catch (_) {}
 
     const onMarkerContextMenu = (e) => {
+      if (!this._editingEnabled) return;
       try { e.preventDefault(); } catch (_) {}
       try { e.stopPropagation(); } catch (_) {}
       try { e.stopImmediatePropagation?.(); } catch (_) {}
@@ -1460,12 +1514,12 @@ export class LabelPlacementController {
       if (!m || !m.el) continue;
 
       if (this._labelsHidden) {
-        m.el.style.display = "none";
+        this.#setMarkerVisibility(m, false, "labelsHidden");
         continue;
       }
 
       if (!model) {
-        m.el.style.display = "none";
+        this.#setMarkerVisibility(m, false, "noModel");
         continue;
       }
 
@@ -1474,16 +1528,20 @@ export class LabelPlacementController {
       model.localToWorld(this._tmpV);
 
       if (this.#isPointClippedBySection(this._tmpV)) {
-        m.el.style.display = "none";
+        this.#setMarkerVisibility(m, false, "clipped");
         continue;
       }
 
-      const ndc = this._tmpV.project(camera);
+      const ndc = this._tmpNdc.copy(this._tmpV).project(camera);
 
-      // Если точка за камерой или далеко за пределами — скрываем
-      const inFront = Number.isFinite(ndc.z) && ndc.z >= -1 && ndc.z <= 1;
-      if (!inFront) {
-        m.el.style.display = "none";
+      // Если точка за камерой или вне кадра — скрываем
+      const ndcFinite = Number.isFinite(ndc.x) && Number.isFinite(ndc.y) && Number.isFinite(ndc.z);
+      const inView = ndcFinite
+        && ndc.x >= -1 && ndc.x <= 1
+        && ndc.y >= -1 && ndc.y <= 1
+        && ndc.z >= -1 && ndc.z <= 1;
+      if (!inView) {
+        this.#setMarkerVisibility(m, false, "outOfView");
         continue;
       }
 
@@ -1491,15 +1549,62 @@ export class LabelPlacementController {
       const y = (-ndc.y * 0.5 + 0.5) * h;
 
       if (!Number.isFinite(x) || !Number.isFinite(y)) {
-        m.el.style.display = "none";
+        this.#setMarkerVisibility(m, false, "invalidScreen");
         continue;
       }
 
-      m.el.style.display = "block";
+      const occluded = this.#isPointOccludedByModel(this._tmpV, ndc, model, camera);
+      if (occluded) {
+        this.#setMarkerVisibility(m, false, "occluded");
+        continue;
+      }
+
+      this.#setMarkerVisibility(m, true, "visible");
       m.el.style.transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%)`;
     }
   }
 
+  #setMarkerVisibility(marker, visible, reason) {
+    if (!marker || !marker.el) return;
+    if (visible) {
+      marker.el.style.display = "block";
+      try { marker.el.classList.remove("ifc-label-marker--hidden"); } catch (_) {}
+    } else {
+      try { marker.el.classList.add("ifc-label-marker--hidden"); } catch (_) {}
+      marker.el.style.display = "block";
+    }
+    if (!this._visibilityLogEnabled) return;
+    if (marker.visible === visible && marker.hiddenReason === reason) return;
+    marker.visible = visible;
+    marker.hiddenReason = reason;
+    this.logger?.log?.("[LabelVisibility]", {
+      id: marker.id,
+      visible,
+      reason,
+    });
+  }
+
+  #isPointOccludedByModel(pointWorld, ndc, model, camera) {
+    if (!pointWorld || !ndc || !model || !camera) return false;
+    this._raycaster.setFromCamera(ndc, camera);
+    const hits = this._raycaster.intersectObject(model, true);
+    if (!hits || hits.length === 0) return false;
+    let hit = null;
+    for (const h of hits) {
+      if (!h || !h.object || !h.object.isMesh) continue;
+      if (this.#isPointClippedBySection(h.point)) continue;
+      hit = h;
+      break;
+    }
+    if (!hit || !Number.isFinite(hit.distance)) return false;
+    const ray = this._raycaster.ray;
+    this._tmpV2.copy(pointWorld).sub(ray.origin);
+    const t = this._tmpV2.dot(ray.direction);
+    if (!Number.isFinite(t) || t <= 0) return false;
+    const epsilon = 1e-2;
+    return hit.distance + epsilon < t;
+  }
+
   #isPointClippedBySection(pointWorld) {
     const planes = this.viewer?.clipping?.planes || [];
     for (const plane of planes) {
@@ -1510,6 +1615,12 @@ export class LabelPlacementController {
     return false;
   }
 
+  #copyMatrix(matrix, cache) {
+    if (!matrix || !cache || cache.length !== 16) return;
+    const e = matrix.elements;
+    for (let i = 0; i < 16; i += 1) cache[i] = e[i] ?? 0;
+  }
+
   #setLabelsHidden(hidden) {
     const next = !!hidden;
     if (this._labelsHidden === next) return;
@@ -1522,6 +1633,72 @@ export class LabelPlacementController {
     this.#syncHideButton();
   }
 
+  #beginAutoHideForControls() {
+    if (!this._autoHide.active) {
+      this._autoHide.prevHidden = this._labelsHidden;
+      this._autoHide.active = true;
+    }
+    this._labelsHidden = true;
+    this.#syncHideButton();
+    this.#cancelShowAfterStop();
+  }
+
+  #scheduleShowAfterStop() {
+    if (!this._autoHide.active) return;
+    const cam = this.viewer?.camera;
+    if (!cam) return;
+    this._showAfterStop.active = true;
+    this._showAfterStop.lastChangeTs = performance.now();
+    this.#copyMatrix(cam.matrixWorld, this._showAfterStop.lastCamMatrix);
+    if (!this._showAfterStop.raf) {
+      this._showAfterStop.raf = requestAnimationFrame(() => this.#tickShowAfterStop());
+    }
+  }
+
+  #cancelShowAfterStop() {
+    if (this._showAfterStop.raf) cancelAnimationFrame(this._showAfterStop.raf);
+    this._showAfterStop.raf = 0;
+    this._showAfterStop.active = false;
+  }
+
+  #tickShowAfterStop() {
+    if (!this._showAfterStop.active) {
+      this._showAfterStop.raf = 0;
+      return;
+    }
+    const cam = this.viewer?.camera;
+    if (!cam) {
+      this._showAfterStop.raf = 0;
+      return;
+    }
+    const now = performance.now();
+    if (!this.#isCameraStable(cam.matrixWorld, this._showAfterStop.lastCamMatrix, this._showAfterStop.eps)) {
+      this._showAfterStop.lastChangeTs = now;
+    }
+    if (now - this._showAfterStop.lastChangeTs >= this._showAfterStop.idleMs) {
+      this._labelsHidden = this._autoHide.prevHidden;
+      this._autoHide.active = false;
+      this.#syncHideButton();
+      this._showAfterStop.active = false;
+      this._showAfterStop.raf = 0;
+      return;
+    }
+    this._showAfterStop.raf = requestAnimationFrame(() => this.#tickShowAfterStop());
+  }
+
+  #isCameraStable(matrix, cache, eps) {
+    if (!matrix || !cache || cache.length !== 16) return true;
+    const e = matrix.elements;
+    let stable = true;
+    for (let i = 0; i < 16; i += 1) {
+      const v = e[i] ?? 0;
+      const d = Math.abs(v - cache[i]);
+      if (d > eps) stable = false;
+      cache[i] = v;
+    }
+    return stable;
+  }
+
   #syncHideButton() {
     const btn = this._ui?.hideBtn;
     if (!btn) return;
@@ -1536,7 +1713,7 @@ export class LabelPlacementController {
   }
 
   #syncAddAvailability() {
-    const disabled = !!this._labelsHidden;
+    const disabled = !!this._labelsHidden || !this._editingEnabled;
     const btn = this._ui?.btn;
     if (btn) {
       btn.disabled = disabled;
@@ -1548,5 +1725,33 @@ export class LabelPlacementController {
       try { menuAdd.classList.toggle("ifc-label-menu-item--disabled", disabled); } catch (_) {}
     }
   }
+
+  #syncEditingUi() {
+    const actions = this._ui?.actions;
+    if (actions) actions.style.display = this._editingEnabled ? "" : "none";
+    if (!this._editingEnabled) {
+      try { this.cancelPlacement(); } catch (_) {}
+      try { this.#closeContextMenu(); } catch (_) {}
+      try { this.#closeCanvasMenu(); } catch (_) {}
+      this._labelDrag.active = false;
+      this._labelDrag.moved = false;
+      this._labelDrag.pointerId = null;
+      this._labelDrag.id = null;
+      this._labelDrag.clickMarker = null;
+      this.#setDragGhostVisible(false);
+    }
+    this.#syncAddAvailability();
+  }
+
+  setEditingEnabled(enabled) {
+    const next = !!enabled;
+    if (this._editingEnabled === next) return;
+    this._editingEnabled = next;
+    this.#syncEditingUi();
+  }
+
+  getEditingEnabled() {
+    return !!this._editingEnabled;
+  }
 }
 

package/src/viewer/Viewer.js

@@ -190,6 +190,15 @@ export class Viewer {
     this._rotAngleEps = 0.01;     // ~0.57° минимальный угловой сдвиг
     this._axisEmaAlpha = 0.15;    // коэффициент сглаживания оси
 
+    this._damping = {
+      dynamic: true,
+      base: 0.5,
+      settle: 0,
+      settleMs: 0,
+      isSettling: false,
+      lastEndTs: 0,
+    };
+
     this._onPointerDown = null;
     this._onPointerUp = null;
     this._onPointerMove = null;
@@ -249,6 +258,53 @@ export class Viewer {
     return { enabled: !!this._zoomToCursor.enabled, debug: !!this._zoomToCursor.debug };
   }
 
+  /**
+   * Возвращает параметры динамического damping (для UI).
+   */
+  getDampingConfig() {
+    const d = this._damping || {};
+    return {
+      dynamic: !!d.dynamic,
+      base: Number.isFinite(d.base) ? d.base : 0,
+      settle: Number.isFinite(d.settle) ? d.settle : 0,
+      settleMs: Number.isFinite(d.settleMs) ? d.settleMs : 0,
+    };
+  }
+
+  /**
+   * Обновляет параметры динамического damping.
+   * @param {{ dynamic?: boolean, base?: number, settle?: number, settleMs?: number }} next
+   */
+  setDampingConfig(next = {}) {
+    if (!this._damping) return;
+    const clamp01 = (v) => Math.min(1, Math.max(0, v));
+    if (Object.prototype.hasOwnProperty.call(next, 'dynamic')) {
+      this._damping.dynamic = !!next.dynamic;
+    }
+    if (Object.prototype.hasOwnProperty.call(next, 'base')) {
+      const v = Number(next.base);
+      if (Number.isFinite(v)) this._damping.base = clamp01(v);
+    }
+    if (Object.prototype.hasOwnProperty.call(next, 'settle')) {
+      const v = Number(next.settle);
+      if (Number.isFinite(v)) this._damping.settle = clamp01(v);
+    }
+    if (Object.prototype.hasOwnProperty.call(next, 'settleMs')) {
+      const v = Number(next.settleMs);
+      if (Number.isFinite(v)) this._damping.settleMs = Math.max(0, v);
+    }
+    if (this.controls) {
+      if (!this._damping.dynamic) {
+        this._damping.isSettling = false;
+        this.controls.enableDamping = false;
+        this.controls.dampingFactor = this._damping.base;
+      } else {
+        this.controls.enableDamping = true;
+        if (!this._damping.isSettling) this.controls.dampingFactor = this._damping.base;
+      }
+    }
+  }
+
   /**
    * Возвращает "домашнюю" точку вращения для текущей модели:
    * центр bbox (совпадает с кадрированием при первичной загрузке).
@@ -701,13 +757,25 @@ export class Viewer {
       const dir = this.camera.position.clone().sub(this.controls.target).normalize();
       this._prevViewDir = dir;
       this._smoothedAxis = null;
+      if (this._damping.dynamic) {
+        this.controls.dampingFactor = this._damping.base;
+        this._damping.isSettling = false;
+        this.controls.enableDamping = true;
+      }
     };
     this._onControlsChange = () => {
       // Обновляем ось только при зажатой ЛКМ (вращение)
       if (!this._isLmbDown) return;
       this.#updateRotationAxisLine();
     };
-    this._onControlsEnd = () => { this.#hideRotationAxisLine(); };
+    this._onControlsEnd = () => {
+      this.#hideRotationAxisLine();
+      if (this._damping.dynamic && this.controls) {
+        this._damping.isSettling = true;
+        this._damping.lastEndTs = performance.now();
+        this.controls.enableDamping = true;
+      }
+    };
     this.controls.addEventListener('start', this._onControlsStart);
     this.controls.addEventListener('change', this._onControlsChange);
     this.controls.addEventListener('end', this._onControlsEnd);
@@ -768,7 +836,10 @@ export class Viewer {
       this.demoCube.rotation.x += 0.005;
     }
 
-    if (this.controls) this.controls.update();
+    if (this.controls) {
+      this.#updateDynamicDamping();
+      this.controls.update();
+    }
     // "Внутренняя" подсветка/пост-эффекты: включаются только когда камера внутри модели
     this.#updateInteriorAssist();
     this._notifyZoomIfChanged();
@@ -814,6 +885,22 @@ export class Viewer {
     this.animationId = requestAnimationFrame(this.animate);
   }
 
+  #updateDynamicDamping() {
+    if (!this.controls) return;
+    if (!this._damping.dynamic || !this.controls.enableDamping) return;
+    if (this._damping.isSettling) {
+      const now = performance.now();
+      if (now - this._damping.lastEndTs <= this._damping.settleMs) {
+        this.controls.dampingFactor = this._damping.settle;
+      } else {
+        this._damping.isSettling = false;
+        this.controls.dampingFactor = this._damping.base;
+      }
+    } else {
+      this.controls.dampingFactor = this._damping.base;
+    }
+  }
+
   dispose() {
     if (this.animationId) cancelAnimationFrame(this.animationId);
     window.removeEventListener("resize", this.handleResize);