Merge develop: Add Boundary Falloff / Live Preview (closes #1)

Integrates PR #1 (Add Boundary Falloff / Live Preview) with additional
fixes and improvements:

- Boundary falloff with configurable distance slider
- Live preview with per-vertex and per-fragment falloff computation
- Smooth view-dependent shading for all mask types (exclude, include-only, angle)
- Mask-type-dependent falloff tinting (orange for user masks, grey for angle masks)
- Italian translations for Boundary Falloff
- Performance: skip falloff computation during active masking
- Fix: boundary vertices start at falloff factor 0
- Fix: trailing comma syntax errors in i18n.js

index.html

@@ -163,6 +163,11 @@
         <div id="amplitude-warning" class="amplitude-warning hidden" data-i18n="warnings.amplitudeOverlap">
           ⚠ Amplitude exceeds 10% of the smallest model dimension — geometry overlaps may occur in the exported STL.
         </div>
+        <div class="form-row slider-row">
+          <label for="boundary-falloff" data-i18n="labels.boundaryFalloff" data-i18n-title="tooltips.boundaryFalloff" title="Gradually reduces displacement to zero near masked boundaries, preventing triangle overlap where textured and non-textured regions meet.">Boundary Falloff ⓘ</label>
+          <input type="range" id="boundary-falloff" min="0" max="10" step="0.1" value="1" />
+          <input type="number" class="val" id="boundary-falloff-val" value="1" min="0" max="10" step="0.1" />
+        </div>
         <div class="form-row">
           <label class="checkbox-label" for="symmetric-displacement"
             data-i18n-title="tooltips.symmetricDisplacement"

js/displacement.js

@@ -180,6 +180,110 @@ export function applyDisplacement(geometry, imageData, imgWidth, imgHeight, sett
     n[0] /= len; n[1] /= len; n[2] /= len;
   });
 
+  // ── Boundary falloff distance field ──────────────────────────────────────────
+  // When boundaryFalloff > 0, identify boundary positions (vertices adjacent to
+  // both masked and unmasked faces, or on the user-exclusion seam) and compute
+  // the Euclidean distance from every fully-textured vertex to its nearest
+  // boundary position.  The result is a falloffMap: posKey → [0, 1] where 0 means
+  // "at the boundary" and 1 means "at or beyond the falloff distance".
+  const boundaryFalloff = settings.boundaryFalloff ?? 0;
+  let falloffMap = null;
+
+  if (boundaryFalloff > 0) {
+    const boundaryPositions = []; // [[x, y, z], ...]
+
+    // Collect boundary positions: vertices where maskedFrac is between 0 and 1,
+    // or that sit on the user-exclusion seam.
+    const posFromKey = new Map(); // posKey → [x, y, z]
+    for (let i = 0; i < count; i++) {
+      tmpPos.fromBufferAttribute(posAttr, i);
+      const k = posKey(tmpPos.x, tmpPos.y, tmpPos.z);
+      if (!posFromKey.has(k)) posFromKey.set(k, [tmpPos.x, tmpPos.y, tmpPos.z]);
+    }
+
+    for (const [k, pos] of posFromKey) {
+      const mf = maskedFracMap.get(k);
+      const maskedFrac = mf && mf[1] > 0 ? mf[0] / mf[1] : 0;
+      const isOnExclBoundary = excludedPosSet && excludedPosSet.has(k);
+      if (isOnExclBoundary || (maskedFrac > 0 && maskedFrac < 1)) {
+        boundaryPositions.push(pos);
+      }
+    }
+
+    if (boundaryPositions.length > 0) {
+      // Build a spatial grid of boundary positions for fast nearest-neighbor lookup
+      let gMinX = Infinity, gMinY = Infinity, gMinZ = Infinity;
+      let gMaxX = -Infinity, gMaxY = -Infinity, gMaxZ = -Infinity;
+      for (const bp of boundaryPositions) {
+        if (bp[0] < gMinX) gMinX = bp[0]; if (bp[0] > gMaxX) gMaxX = bp[0];
+        if (bp[1] < gMinY) gMinY = bp[1]; if (bp[1] > gMaxY) gMaxY = bp[1];
+        if (bp[2] < gMinZ) gMinZ = bp[2]; if (bp[2] > gMaxZ) gMaxZ = bp[2];
+      }
+      const gPad = boundaryFalloff + 1e-3;
+      gMinX -= gPad; gMinY -= gPad; gMinZ -= gPad;
+      gMaxX += gPad; gMaxY += gPad; gMaxZ += gPad;
+
+      const gRes = Math.max(4, Math.min(128, Math.ceil(Math.cbrt(boundaryPositions.length) * 2)));
+      const gDx = (gMaxX - gMinX) / gRes || 1;
+      const gDy = (gMaxY - gMinY) / gRes || 1;
+      const gDz = (gMaxZ - gMinZ) / gRes || 1;
+      const bGrid = new Map();
+      const bCellKey = (ix, iy, iz) => (ix * gRes + iy) * gRes + iz;
+
+      for (const bp of boundaryPositions) {
+        const ix = Math.max(0, Math.min(gRes - 1, Math.floor((bp[0] - gMinX) / gDx)));
+        const iy = Math.max(0, Math.min(gRes - 1, Math.floor((bp[1] - gMinY) / gDy)));
+        const iz = Math.max(0, Math.min(gRes - 1, Math.floor((bp[2] - gMinZ) / gDz)));
+        const ck = bCellKey(ix, iy, iz);
+        const cell = bGrid.get(ck);
+        if (cell) cell.push(bp); else bGrid.set(ck, [bp]);
+      }
+
+      // How many grid cells to search in each direction to cover boundaryFalloff distance
+      const searchX = Math.ceil(boundaryFalloff / gDx);
+      const searchY = Math.ceil(boundaryFalloff / gDy);
+      const searchZ = Math.ceil(boundaryFalloff / gDz);
+
+      falloffMap = new Map();
+      for (const [k, pos] of posFromKey) {
+        const mf = maskedFracMap.get(k);
+        const maskedFrac = mf && mf[1] > 0 ? mf[0] / mf[1] : 0;
+        const isOnExclBoundary = excludedPosSet && excludedPosSet.has(k);
+        // Only compute falloff for fully-textured, non-boundary positions
+        if (maskedFrac > 0 || isOnExclBoundary) continue;
+
+        const px = pos[0], py = pos[1], pz = pos[2];
+        const cix = Math.max(0, Math.min(gRes - 1, Math.floor((px - gMinX) / gDx)));
+        const ciy = Math.max(0, Math.min(gRes - 1, Math.floor((py - gMinY) / gDy)));
+        const ciz = Math.max(0, Math.min(gRes - 1, Math.floor((pz - gMinZ) / gDz)));
+
+        let minDist2 = boundaryFalloff * boundaryFalloff;
+        for (let dix = -searchX; dix <= searchX; dix++) {
+          const nix = cix + dix;
+          if (nix < 0 || nix >= gRes) continue;
+          for (let diy = -searchY; diy <= searchY; diy++) {
+            const niy = ciy + diy;
+            if (niy < 0 || niy >= gRes) continue;
+            for (let diz = -searchZ; diz <= searchZ; diz++) {
+              const niz = ciz + diz;
+              if (niz < 0 || niz >= gRes) continue;
+              const cell = bGrid.get(bCellKey(nix, niy, niz));
+              if (!cell) continue;
+              for (const bp of cell) {
+                const dx = px - bp[0], dy = py - bp[1], dz = pz - bp[2];
+                const d2 = dx * dx + dy * dy + dz * dz;
+                if (d2 < minDist2) minDist2 = d2;
+              }
+            }
+          }
+        }
+        const dist = Math.sqrt(minDist2);
+        const factor = Math.min(1, dist / boundaryFalloff);
+        if (factor < 1) falloffMap.set(k, factor);
+      }
+    }
+  }
+
   // ── Pass 2: sample displacement texture once per unique position ──────────
   const dispCache = new Map(); // posKey → grey [0, 1]
 
@@ -272,7 +376,8 @@ export function applyDisplacement(geometry, imageData, imgWidth, imgHeight, sett
     const mf         = maskedFracMap.get(k) || [0, 1];
     const maskedFrac = mf[1] > 0 ? mf[0] / mf[1] : 0;
     const centeredGrey = settings.symmetricDisplacement ? (grey - 0.5) : grey;
-    const disp = (isFaceExcluded || isSealedBoundary) ? 0 : (1 - maskedFrac) * centeredGrey * settings.amplitude;
+    const falloffFactor = (falloffMap && falloffMap.has(k)) ? falloffMap.get(k) : 1.0;
+    const disp = (isFaceExcluded || isSealedBoundary) ? 0 : falloffFactor * (1 - maskedFrac) * centeredGrey * settings.amplitude;
 
     const newX = tmpPos.x + sn[0] * disp;
     const newY = tmpPos.y + sn[1] * disp;

js/i18n.js

@@ -107,6 +107,10 @@ export const TRANSLATIONS = {
     'precision.refining': 'Refining\u2026',
     'precision.warningBody': 'Estimated ~{n} triangles. This may slow down your browser. Continue?',
 
+    // Boundary falloff
+    'labels.boundaryFalloff':          'Boundary Falloff \u24d8',
+    'tooltips.boundaryFalloff':        'Gradually reduces displacement to zero near masked boundaries, preventing triangle overlap where textured and non-textured regions meet.',
+
     // Symmetric displacement
     'labels.symmetricDisplacement': 'Symmetric displacement \u24d8',
     'tooltips.symmetricDisplacement': 'When on, 50% grey = no displacement; white pushes out, black pushes in. Keeps part volume roughly constant.',
@@ -293,6 +297,10 @@ export const TRANSLATIONS = {
     'precision.refining': 'Wird verfeinert\u2026',
     'precision.warningBody': 'Gesch\u00e4tzt ~{n} Dreiecke. Dies kann den Browser verlangsamen. Fortfahren?',
 
+    // Boundary falloff
+    'labels.boundaryFalloff':          'Rand\u00fcbergang \u24d8',
+    'tooltips.boundaryFalloff':        'Reduziert die Verschiebung schrittweise auf Null nahe maskierter Grenzen, um Dreiecks\u00fcberschneidungen an \u00dcberg\u00e4ngen zu vermeiden.',
+
     // Symmetric displacement
     'labels.symmetricDisplacement': 'Symmetrische Verschiebung \u24d8',
     'tooltips.symmetricDisplacement': 'Wenn aktiv: 50% Grau = keine Verschiebung; Weiß nach außen, Schwarz nach innen. H\u00e4lt das Volumen des Teils in etwa konstant.',
@@ -479,6 +487,10 @@ export const TRANSLATIONS = {
     'precision.refining': 'Raffinamento\u2026',
     'precision.warningBody': 'Stima ~{n} triangoli. Ciò potrebbe rallentare il browser. Continuare?',
 
+    // Boundary falloff
+    'labels.boundaryFalloff':          'Sfumatura bordo \u24d8',
+    'tooltips.boundaryFalloff':        'Riduce gradualmente la deformazione a zero vicino ai bordi mascherati, impedendo sovrapposizioni di triangoli tra zone con e senza texture.',
+
     // Symmetric displacement
     'labels.symmetricDisplacement': 'Deformazione simmetrica \u24d8',
     'tooltips.symmetricDisplacement': 'Quando è attivo, il grigio al 50% = nessuna deformazione; il bianco spinge verso l\'esterno, il nero spinge verso l\'interno. Mantiene il volume della parte approssimativamente costante.',

js/main.js

@@ -23,6 +23,12 @@ let previewMaterial   = null;
 let isExporting       = false;
 let previewDebounce   = null;
 
+// Boundary edge data texture for per-fragment falloff in bump-only preview
+let _boundaryEdgeTex   = null;
+let _boundaryEdgeCount = 0;
+let _falloffDirty      = true;   // recompute falloff on next updateFaceMask
+let _falloffGeometry   = null;   // geometry the falloff was last computed for
+
 // ── Exclusion state ───────────────────────────────────────────────────────────
 let excludedFaces      = new Set();   // triangle indices in currentGeometry
 let triangleAdjacency  = null;        // Map from buildAdjacency
@@ -56,6 +62,7 @@ const settings = {
   seamBandWidth:    0.5,
   textureSmoothing: 0,
   capAngle:         20,
+  boundaryFalloff:  1,
   symmetricDisplacement: false,
   useDisplacement: false,
 };
@@ -201,6 +208,8 @@ const textureSmoothingVal    = document.getElementById('texture-smoothing-val');
 const capAngleSlider         = document.getElementById('cap-angle');
 const capAngleVal            = document.getElementById('cap-angle-val');
 const capAngleRow            = document.getElementById('cap-angle-row');
+const boundaryFalloffSlider    = document.getElementById('boundary-falloff');
+const boundaryFalloffVal       = document.getElementById('boundary-falloff-val');
 const symmetricDispToggle    = document.getElementById('symmetric-displacement');
 const dispPreviewToggle      = document.getElementById('displacement-preview');
 
@@ -457,10 +466,11 @@ function wireEvents() {
   linkSlider(rotationSlider,  rotationVal,  v => { settings.rotation  = v; return Math.round(v); });
   linkSlider(amplitudeSlider, amplitudeVal, v => { settings.amplitude = v; checkAmplitudeWarning(); return v.toFixed(2); });
   amplitudeVal.addEventListener('change', checkAmplitudeWarning);
+  linkSlider(boundaryFalloffSlider, boundaryFalloffVal, v => { settings.boundaryFalloff = v; _falloffDirty = true; return v.toFixed(1); });
   linkSlider(refineLenSlider, refineLenVal, v => { settings.refineLength  = v; return v.toFixed(2); }, false);
   linkSlider(maxTriSlider, maxTriVal, v => { settings.maxTriangles = v; return formatM(v); }, false);
-  linkSlider(bottomAngleLimitSlider, bottomAngleLimitVal, v => { settings.bottomAngleLimit = v; return v; });
+  linkSlider(bottomAngleLimitSlider, bottomAngleLimitVal, v => { settings.bottomAngleLimit = v; _falloffDirty = true; return v; });
-  linkSlider(topAngleLimitSlider,    topAngleLimitVal,    v => { settings.topAngleLimit    = v; return v; });
+  linkSlider(topAngleLimitSlider,    topAngleLimitVal,    v => { settings.topAngleLimit    = v; _falloffDirty = true; return v; });
   linkSlider(seamBlendSlider,        seamBlendVal,        v => { settings.mappingBlend     = v; return v.toFixed(2); });
   linkSlider(seamBandWidthSlider,    seamBandWidthVal,    v => { settings.seamBandWidth    = v; return v.toFixed(2); });
   linkSlider(textureSmoothingSlider, textureSmoothingVal, v => { settings.textureSmoothing = v; return v.toFixed(1); });
@@ -763,6 +773,12 @@ function setExclusionTool(tool) {
   if (!exclusionTool) {
     isPainting = false;
     getControls().enabled = true;
+    // Recompute boundary falloff now that masking is done
+    if (_falloffDirty && currentGeometry) {
+      const activeGeo = (settings.useDisplacement && dispPreviewGeometry)
+        ? dispPreviewGeometry : currentGeometry;
+      updateFaceMask(activeGeo);
+    }
   }
 }
 
@@ -1087,12 +1103,11 @@ function refreshExclusionOverlay() {
   const overlayGeo = usePrecision ? precisionGeometry : currentGeometry;
   const overlayFaceSet = usePrecision ? precisionExcludedFaces : excludedFaces;
 
-  if (selectionMode) {
+  _falloffDirty = true;
-    const maskGeo = buildExclusionOverlayGeo(overlayGeo, overlayFaceSet, true);
+
-    setExclusionOverlay(maskGeo, 0x8ab4d4, 0.96);
+  // Never show the flat-coloured MeshLambertMaterial overlay — the custom
-  } else {
+  // shader handles mask visualisation with smooth, view-dependent shading.
-    setExclusionOverlay(buildExclusionOverlayGeo(overlayGeo, overlayFaceSet), 0xff6600);
+  setExclusionOverlay(null);
-  }
   const n = usePrecision ? precisionExcludedFaces.size : excludedFaces.size;
   exclCount.textContent = selectionMode
     ? t(n === 1 ? 'excl.faceSelected' : 'excl.facesSelected', { n: n.toLocaleString() })
@@ -1488,6 +1503,329 @@ function updateFaceMask(geometry) {
   if (!geometry.attributes.faceNormal) {
     addFaceNormals(geometry);
   }
+
+  // Skip expensive falloff recomputation while actively masking;
+  // it will be recalculated when the masking tool is deactivated.
+  if (!exclusionTool && (_falloffDirty || geometry !== _falloffGeometry)) {
+    computeBoundaryFalloffAttr(geometry, maskArr);
+    computeBoundaryEdges(geometry, maskArr);
+    _falloffDirty = false;
+    _falloffGeometry = geometry;
+  }
+  syncBoundaryEdgeUniforms();
+}
+
+/**
+ * Compute a per-vertex `boundaryFalloffAttr` float attribute on the geometry.
+ * Vertices near the boundary between masked and non-masked regions get values
+ * ramping from 0 (at boundary) to 1 (at or beyond boundaryFalloff distance).
+ * The shader multiplies displacement/bump by this attribute.
+ *
+ * @param {THREE.BufferGeometry} geometry
+ * @param {Float32Array}         userMaskArr – per-vertex user-exclusion mask from updateFaceMask
+ */
+function computeBoundaryFalloffAttr(geometry, userMaskArr) {
+  const posAttr = geometry.attributes.position;
+  const posCount = posAttr.count;
+  const triCount = posCount / 3;
+  const falloff = settings.boundaryFalloff ?? 0;
+  const falloffArr = new Float32Array(posCount);
+  falloffArr.fill(1.0);
+
+  if (falloff <= 0) {
+    geometry.setAttribute('boundaryFalloffAttr', new THREE.Float32BufferAttribute(falloffArr, 1));
+    const defaultType = new Float32Array(posCount);
+    defaultType.fill(1.0);
+    geometry.setAttribute('boundaryMaskTypeAttr', new THREE.Float32BufferAttribute(defaultType, 1));
+    return;
+  }
+
+  // Compute per-face combined mask (angle masking + user exclusion).
+  // Mirrors the vertex shader logic so the preview boundary matches export.
+  const faceNrmAttr = geometry.attributes.faceNormal;
+  const faceMask = new Float32Array(triCount); // 0 = masked, 1 = textured
+  const isUserMasked = new Uint8Array(triCount); // 1 if user-excluded
+  for (let t = 0; t < triCount; t++) {
+    const userVal = userMaskArr[t * 3]; // same for all 3 verts of this face
+    if (userVal < 0.5) { faceMask[t] = 0; isUserMasked[t] = 1; continue; }
+
+    let angleMask = 1.0;
+    if (faceNrmAttr) {
+      const fnz = faceNrmAttr.getZ(t * 3);
+      const fnx = faceNrmAttr.getX(t * 3);
+      const fny = faceNrmAttr.getY(t * 3);
+      const len = Math.sqrt(fnx * fnx + fny * fny + fnz * fnz);
+      const nz = len > 1e-6 ? fnz / len : 0;
+      const surfaceAngle = Math.acos(Math.min(1, Math.abs(nz))) * (180 / Math.PI);
+      if (nz < 0 && settings.bottomAngleLimit >= 1)
+        angleMask = surfaceAngle > settings.bottomAngleLimit ? 1.0 : 0.0;
+      if (nz >= 0 && settings.topAngleLimit >= 1)
+        angleMask = Math.min(angleMask, surfaceAngle > settings.topAngleLimit ? 1.0 : 0.0);
+    }
+    faceMask[t] = angleMask;
+  }
+
+  // Build per-unique-position map and identify boundary positions.
+  const QUANT = 1e4;
+  const posKey = (x, y, z) =>
+    `${Math.round(x * QUANT)}_${Math.round(y * QUANT)}_${Math.round(z * QUANT)}`;
+
+  const posFromKey = new Map();  // posKey → [x, y, z]
+  // Per-position: [maskedArea, totalArea] to find boundary vertices
+  const maskFracMap = new Map();
+  const userMaskAreaMap = new Map(); // posKey → area of user-masked faces
+  const tmpV = new THREE.Vector3();
+  const vA = new THREE.Vector3(), vB = new THREE.Vector3(), vC = new THREE.Vector3();
+  const e1 = new THREE.Vector3(), e2 = new THREE.Vector3(), fn = new THREE.Vector3();
+
+  for (let t = 0; t < triCount; t++) {
+    vA.fromBufferAttribute(posAttr, t * 3);
+    vB.fromBufferAttribute(posAttr, t * 3 + 1);
+    vC.fromBufferAttribute(posAttr, t * 3 + 2);
+    e1.subVectors(vB, vA);
+    e2.subVectors(vC, vA);
+    fn.crossVectors(e1, e2);
+    const area = fn.length();
+    const masked = faceMask[t] < 0.5;
+
+    for (let v = 0; v < 3; v++) {
+      tmpV.fromBufferAttribute(posAttr, t * 3 + v);
+      const k = posKey(tmpV.x, tmpV.y, tmpV.z);
+      if (!posFromKey.has(k)) posFromKey.set(k, [tmpV.x, tmpV.y, tmpV.z]);
+      const mf = maskFracMap.get(k);
+      if (mf) {
+        if (masked) mf[0] += area;
+        mf[1] += area;
+      } else {
+        maskFracMap.set(k, [masked ? area : 0, area]);
+      }
+      // Track user-mask area per position to classify boundary type
+      if (isUserMasked[t]) {
+        const prev = userMaskAreaMap.get(k) || 0;
+        userMaskAreaMap.set(k, prev + area);
+      }
+    }
+  }
+
+  // Boundary positions: shared between masked and non-masked faces.
+  // Each entry: [x, y, z, maskType] where maskType 0 = user, 1 = angle.
+  const boundaryPositions = [];
+  for (const [k, pos] of posFromKey) {
+    const mf = maskFracMap.get(k);
+    const frac = mf[1] > 0 ? mf[0] / mf[1] : 0;
+    if (frac > 0 && frac < 1) {
+      const userArea = userMaskAreaMap.get(k) || 0;
+      boundaryPositions.push([pos[0], pos[1], pos[2], userArea > 0 ? 0 : 1]);
+    }
+  }
+
+  if (boundaryPositions.length === 0) {
+    geometry.setAttribute('boundaryFalloffAttr', new THREE.Float32BufferAttribute(falloffArr, 1));
+    const defaultType = new Float32Array(posCount);
+    defaultType.fill(1.0);
+    geometry.setAttribute('boundaryMaskTypeAttr', new THREE.Float32BufferAttribute(defaultType, 1));
+    return;
+  }
+
+  // Spatial grid of boundary positions for fast nearest-neighbor search
+  let gMinX = Infinity, gMinY = Infinity, gMinZ = Infinity;
+  let gMaxX = -Infinity, gMaxY = -Infinity, gMaxZ = -Infinity;
+  for (const bp of boundaryPositions) {
+    if (bp[0] < gMinX) gMinX = bp[0]; if (bp[0] > gMaxX) gMaxX = bp[0];
+    if (bp[1] < gMinY) gMinY = bp[1]; if (bp[1] > gMaxY) gMaxY = bp[1];
+    if (bp[2] < gMinZ) gMinZ = bp[2]; if (bp[2] > gMaxZ) gMaxZ = bp[2];
+  }
+  const gPad = falloff + 1e-3;
+  gMinX -= gPad; gMinY -= gPad; gMinZ -= gPad;
+  gMaxX += gPad; gMaxY += gPad; gMaxZ += gPad;
+
+  const gRes = Math.max(4, Math.min(128, Math.ceil(Math.cbrt(boundaryPositions.length) * 2)));
+  const gDx = (gMaxX - gMinX) / gRes || 1;
+  const gDy = (gMaxY - gMinY) / gRes || 1;
+  const gDz = (gMaxZ - gMinZ) / gRes || 1;
+  const bGrid = new Map();
+  const bCellKey = (ix, iy, iz) => (ix * gRes + iy) * gRes + iz;
+
+  for (const bp of boundaryPositions) {
+    const ix = Math.max(0, Math.min(gRes - 1, Math.floor((bp[0] - gMinX) / gDx)));
+    const iy = Math.max(0, Math.min(gRes - 1, Math.floor((bp[1] - gMinY) / gDy)));
+    const iz = Math.max(0, Math.min(gRes - 1, Math.floor((bp[2] - gMinZ) / gDz)));
+    const ck = bCellKey(ix, iy, iz);
+    const cell = bGrid.get(ck);
+    if (cell) cell.push(bp); else bGrid.set(ck, [bp]);
+  }
+
+  const searchX = Math.ceil(falloff / gDx);
+  const searchY = Math.ceil(falloff / gDy);
+  const searchZ = Math.ceil(falloff / gDz);
+
+  // Compute per-unique-position falloff factor and mask type
+  const falloffCache = new Map(); // posKey → factor [0,1]
+  const maskTypeCache = new Map(); // posKey → 0 (user mask) or 1 (angle mask)
+  for (const [k, pos] of posFromKey) {
+    const mf = maskFracMap.get(k);
+    const frac = mf[1] > 0 ? mf[0] / mf[1] : 0;
+    if (frac >= 1) continue; // fully masked vertex — keep 1.0 (mask zeroes it anyway)
+    // Boundary vertices (shared between masked and unmasked faces) are AT
+    // the boundary → distance 0 → falloff factor 0.
+    if (frac > 0) {
+      falloffCache.set(k, 0);
+      const userArea = userMaskAreaMap.get(k) || 0;
+      maskTypeCache.set(k, userArea > 0 ? 0 : 1);
+      continue;
+    }
+
+    const px = pos[0], py = pos[1], pz = pos[2];
+    const cix = Math.max(0, Math.min(gRes - 1, Math.floor((px - gMinX) / gDx)));
+    const ciy = Math.max(0, Math.min(gRes - 1, Math.floor((py - gMinY) / gDy)));
+    const ciz = Math.max(0, Math.min(gRes - 1, Math.floor((pz - gMinZ) / gDz)));
+
+    let minDist2 = falloff * falloff;
+    let nearestType = 1; // default: angle mask
+    for (let dix = -searchX; dix <= searchX; dix++) {
+      const nix = cix + dix;
+      if (nix < 0 || nix >= gRes) continue;
+      for (let diy = -searchY; diy <= searchY; diy++) {
+        const niy = ciy + diy;
+        if (niy < 0 || niy >= gRes) continue;
+        for (let diz = -searchZ; diz <= searchZ; diz++) {
+          const niz = ciz + diz;
+          if (niz < 0 || niz >= gRes) continue;
+          const cell = bGrid.get(bCellKey(nix, niy, niz));
+          if (!cell) continue;
+          for (const bp of cell) {
+            const dx = px - bp[0], dy = py - bp[1], dz = pz - bp[2];
+            const d2 = dx * dx + dy * dy + dz * dz;
+            if (d2 < minDist2) { minDist2 = d2; nearestType = bp[3]; }
+          }
+        }
+      }
+    }
+    const dist = Math.sqrt(minDist2);
+    const factor = Math.min(1, dist / falloff);
+    if (factor < 1) {
+      falloffCache.set(k, factor);
+      maskTypeCache.set(k, nearestType);
+    }
+  }
+
+  // Write per-vertex attributes
+  const maskTypeArr = new Float32Array(posCount);
+  maskTypeArr.fill(1.0); // default: angle mask (grey)
+  for (let i = 0; i < posCount; i++) {
+    tmpV.fromBufferAttribute(posAttr, i);
+    const k = posKey(tmpV.x, tmpV.y, tmpV.z);
+    if (falloffCache.has(k)) falloffArr[i] = falloffCache.get(k);
+    if (maskTypeCache.has(k)) maskTypeArr[i] = maskTypeCache.get(k);
+  }
+
+  geometry.setAttribute('boundaryFalloffAttr', new THREE.Float32BufferAttribute(falloffArr, 1));
+  geometry.setAttribute('boundaryMaskTypeAttr', new THREE.Float32BufferAttribute(maskTypeArr, 1));
+}
+
+/**
+ * Compute boundary edge segments between masked and non-masked faces and
+ * pack them into a DataTexture for per-fragment distance queries in the
+ * bump-only preview shader.  Each edge is stored as two RGBA texels
+ * (endpoint A xyz, endpoint B xyz).
+ */
+function computeBoundaryEdges(geometry, userMaskArr) {
+  const posAttr = geometry.attributes.position;
+  const posCount = posAttr.count;
+  const triCount = posCount / 3;
+  const falloff = settings.boundaryFalloff ?? 0;
+
+  if (_boundaryEdgeTex) { _boundaryEdgeTex.dispose(); _boundaryEdgeTex = null; }
+  _boundaryEdgeCount = 0;
+  if (falloff <= 0) return;
+
+  const faceNrmAttr = geometry.attributes.faceNormal;
+  const faceMaskBool = new Uint8Array(triCount);
+  for (let t = 0; t < triCount; t++) {
+    if (userMaskArr[t * 3] < 0.5) { faceMaskBool[t] = 0; continue; }
+    let angleMask = 1.0;
+    if (faceNrmAttr) {
+      const fnx = faceNrmAttr.getX(t * 3);
+      const fny = faceNrmAttr.getY(t * 3);
+      const fnz = faceNrmAttr.getZ(t * 3);
+      const len = Math.sqrt(fnx * fnx + fny * fny + fnz * fnz);
+      const nz = len > 1e-6 ? fnz / len : 0;
+      const surfAngle = Math.acos(Math.min(1, Math.abs(nz))) * (180 / Math.PI);
+      if (nz < 0 && settings.bottomAngleLimit >= 1)
+        angleMask = surfAngle > settings.bottomAngleLimit ? 1.0 : 0.0;
+      if (nz >= 0 && settings.topAngleLimit >= 1)
+        angleMask = Math.min(angleMask, surfAngle > settings.topAngleLimit ? 1.0 : 0.0);
+    }
+    faceMaskBool[t] = angleMask > 0.5 ? 1 : 0;
+  }
+
+  const QUANT = 1e4;
+  const pk = (x, y, z) =>
+    `${Math.round(x * QUANT)}_${Math.round(y * QUANT)}_${Math.round(z * QUANT)}`;
+  const ek = (k1, k2) => k1 < k2 ? k1 + '|' + k2 : k2 + '|' + k1;
+  const tmpV = new THREE.Vector3();
+
+  const edgeFaces = new Map();
+  const edgePos   = new Map();
+
+  for (let t = 0; t < triCount; t++) {
+    const keys = [], pts = [];
+    for (let v = 0; v < 3; v++) {
+      tmpV.fromBufferAttribute(posAttr, t * 3 + v);
+      keys.push(pk(tmpV.x, tmpV.y, tmpV.z));
+      pts.push([tmpV.x, tmpV.y, tmpV.z]);
+    }
+    for (let e = 0; e < 3; e++) {
+      const edgeKey = ek(keys[e], keys[(e + 1) % 3]);
+      const list = edgeFaces.get(edgeKey);
+      if (list) list.push(t);
+      else {
+        edgeFaces.set(edgeKey, [t]);
+        edgePos.set(edgeKey, [pts[e], pts[(e + 1) % 3]]);
+      }
+    }
+  }
+
+  const MAX_EDGES = 64;
+  const edges = [];
+  for (const [key, faces] of edgeFaces) {
+    if (edges.length >= MAX_EDGES) break;
+    let hasMasked = false, hasTextured = false;
+    for (const f of faces) {
+      if (faceMaskBool[f] === 0) hasMasked = true;
+      else hasTextured = true;
+      if (hasMasked && hasTextured) break;
+    }
+    if (hasMasked && hasTextured) edges.push(edgePos.get(key));
+  }
+
+  if (edges.length === 0) return;
+
+  const texWidth = edges.length * 2;
+  const data = new Float32Array(texWidth * 4);
+  for (let i = 0; i < edges.length; i++) {
+    const [a, b] = edges[i];
+    const off = i * 8;
+    data[off] = a[0]; data[off + 1] = a[1]; data[off + 2] = a[2]; data[off + 3] = 0;
+    data[off + 4] = b[0]; data[off + 5] = b[1]; data[off + 6] = b[2]; data[off + 7] = 0;
+  }
+
+  _boundaryEdgeTex = new THREE.DataTexture(data, texWidth, 1, THREE.RGBAFormat, THREE.FloatType);
+  _boundaryEdgeTex.minFilter = THREE.NearestFilter;
+  _boundaryEdgeTex.magFilter = THREE.NearestFilter;
+  _boundaryEdgeTex.needsUpdate = true;
+  _boundaryEdgeCount = edges.length;
+}
+
+function syncBoundaryEdgeUniforms() {
+  if (!previewMaterial || !previewMaterial.uniforms.boundaryEdgeTex) return;
+  const u = previewMaterial.uniforms;
+  if (_boundaryEdgeTex) {
+    u.boundaryEdgeTex.value = _boundaryEdgeTex;
+    u.boundaryEdgeTexWidth.value = _boundaryEdgeTex.image.width;
+  }
+  u.boundaryEdgeCount.value = _boundaryEdgeCount;
+  u.boundaryFalloffDist.value = settings.boundaryFalloff ?? 0;
 }
 
 /**
@@ -1693,6 +2031,7 @@ function updatePreview() {
     updateMaterial(previewMaterial, effectiveEntry.texture, fullSettings);
   }
 
+  syncBoundaryEdgeUniforms();
   exportBtn.disabled = false;
 }
 

js/previewMaterial.js

@@ -202,12 +202,17 @@ const vertexShader = /* glsl */`
   attribute vec3  smoothNormal;
   attribute vec3  faceNormal;
   attribute float faceMask;
+  attribute float boundaryFalloffAttr;
+  attribute float boundaryMaskTypeAttr;
 
   varying vec3  vModelPos;    // ORIGINAL model-space position → UV computation in fragment
   varying vec3  vModelNormal; // model-space face normal       → stable UV blending
   varying vec3  vViewPos;     // view-space position (possibly displaced) → TBN & specular
   varying vec3  vNormal;      // view-space normal → lighting
-  varying float vFaceMask;    // combined mask (angle + user exclusion)
+  varying vec3  vSmoothNormal; // view-space smooth normal → smooth shading on masked faces
+  varying float vFaceMask;    // combined mask (angle + user exclusion + boundary falloff)
+  varying float vUserMask;    // raw user-exclusion mask (0 = user-excluded, 1 = included)
+  varying float vMaskType;    // boundary mask type (0 = user mask, 1 = angle mask)
 
   void main() {
     vec3 safeN = length(normal) > 1e-6 ? normalize(normal) : vec3(0.0, 0.0, 1.0);
@@ -223,8 +228,10 @@ const vertexShader = /* glsl */`
       angleMask = min(angleMask, surfaceAngle > bottomAngleLimit ? 1.0 : 0.0);
     if (fN.z >= 0.0 && topAngleLimit >= 1.0)
       angleMask = min(angleMask, surfaceAngle > topAngleLimit ? 1.0 : 0.0);
-    float totalMask = angleMask * faceMask;
+    float totalMask = angleMask * faceMask * boundaryFalloffAttr;
     vFaceMask = totalMask;
+    vUserMask = faceMask;
+    vMaskType = boundaryMaskTypeAttr;
 
     if (useDisplacement == 1) {
       float h = computeHeightAtPoint(position, safeN, safeN);
@@ -243,6 +250,8 @@ const vertexShader = /* glsl */`
     vec4 mvPos   = modelViewMatrix * vec4(pos, 1.0);
     vViewPos     = mvPos.xyz;
     vNormal      = normalize(normalMatrix * fN);
+    vec3 sN = length(smoothNormal) > 1e-6 ? normalize(smoothNormal) : safeN;
+    vSmoothNormal = normalize(normalMatrix * sN);
     gl_Position  = projectionMatrix * mvPos;
   }
 `;
@@ -251,11 +260,19 @@ const fragmentShader = /* glsl */`
   precision highp float;
   ${sharedGLSL}
 
+  uniform sampler2D boundaryEdgeTex;
+  uniform int       boundaryEdgeCount;
+  uniform float     boundaryEdgeTexWidth;
+  uniform float     boundaryFalloffDist;
+
   varying vec3  vModelPos;
   varying vec3  vModelNormal;
   varying vec3  vViewPos;
   varying vec3  vNormal;
+  varying vec3  vSmoothNormal;
   varying float vFaceMask;
+  varying float vUserMask;
+  varying float vMaskType;
 
   // Fragment-only wrapper: compute face-stable projection normal via dFdx
   // then delegate to the shared height function.
@@ -282,6 +299,27 @@ const fragmentShader = /* glsl */`
 
     // ── Combined mask (angle + user exclusion) from vertex shader ────────
     float maskBlend = vFaceMask;
+
+    // Per-fragment boundary falloff for bump-only mode.  On coarse meshes the
+    // vertex attribute cannot produce a gradient (too few vertices), so we
+    // compute the distance from each pixel to the nearest boundary edge.
+    if (useDisplacement == 0 && boundaryFalloffDist > 0.001 && boundaryEdgeCount > 0) {
+      float minDist = boundaryFalloffDist;
+      for (int i = 0; i < 64; i++) {
+        if (i >= boundaryEdgeCount) break;
+        float uA = (float(i * 2) + 0.5) / boundaryEdgeTexWidth;
+        float uB = (float(i * 2 + 1) + 0.5) / boundaryEdgeTexWidth;
+        vec3 ea = texture2D(boundaryEdgeTex, vec2(uA, 0.5)).xyz;
+        vec3 eb = texture2D(boundaryEdgeTex, vec2(uB, 0.5)).xyz;
+        vec3 ab = eb - ea;
+        float abLen2 = dot(ab, ab);
+        float t = clamp(dot(vModelPos - ea, ab) / max(abLen2, 1e-10), 0.0, 1.0);
+        float d = length(vModelPos - (ea + t * ab));
+        if (d < minDist) { minDist = d; if (d < 1e-4) break; }
+      }
+      maskBlend *= clamp(minDist / boundaryFalloffDist, 0.0, 1.0);
+    }
+
     h *= maskBlend;
     dhx *= maskBlend;
     dhy *= maskBlend;
@@ -306,8 +344,20 @@ const fragmentShader = /* glsl */`
     vec3 bumpVec = N - bumpStr * (dhx * T + dhy * B);
     vec3 bumpN = length(bumpVec) > 1e-6 ? normalize(bumpVec) : N;
 
+    // On fully masked faces the bump derivatives are zero, so bumpN falls
+    // back to the flat face normal → faceted/static look.  Blend toward
+    // the smooth interpolated normal so masked areas get smooth shading.
+    vec3 smoothN = normalize(vSmoothNormal) * (gl_FrontFacing ? 1.0 : -1.0);
+    bumpN = mix(smoothN, bumpN, maskBlend);
+
     // ── Shading ───────────────────────────────────────────────────────────
-    vec3 baseColor = mix(vec3(0.50, 0.50, 0.50), vec3(0.22, 0.68, 0.68), maskBlend);
+    // Compute lighting identically for ALL surfaces using the teal base so
+    // that specular highlights, diffuse response, and view-dependent shading
+    // are perfectly consistent everywhere.  Mask tinting is applied AFTER
+    // lighting as a colour blend so masked areas keep the same glossy look.
+    vec3 tealBase      = vec3(0.22, 0.68, 0.68);
+    vec3 userMaskColor = vec3(0.85, 0.40, 0.15);
+    vec3 angleMaskColor = vec3(0.45, 0.48, 0.50);
 
     vec3 L1 = normalize(vec3( 0.5,  0.8,  1.0));
     vec3 L2 = normalize(vec3(-0.5, -0.2, -0.6));
@@ -319,10 +369,23 @@ const fragmentShader = /* glsl */`
     vec3 H1   = normalize(L1 + V);
     float spec = pow(max(dot(bumpN, H1), 0.0), 64.0) * 0.60;
 
-    vec3 color = baseColor * 0.55                                        // ambient
+    // Lit teal (identical for textured and masked surfaces)
-               + baseColor * diff1 * vec3(1.00, 0.96, 0.88) * 0.55      // key light
+    vec3 litTeal = tealBase * 0.55
-               + baseColor * diff2 * vec3(0.80, 0.60, 0.50) * 0.15      // warm fill
+                 + tealBase * diff1 * vec3(1.00, 0.96, 0.88) * 0.55
-               + vec3(spec);                                             // specular
+                 + tealBase * diff2 * vec3(0.80, 0.60, 0.50) * 0.15
+                 + vec3(spec);
+
+    // Mask tint: pick colour by mask type, compute same lighting with that base
+    float maskEffect = 1.0 - maskBlend; // 0 = fully textured, 1 = fully masked
+    float effectiveMaskType = mix(vMaskType, 0.0, step(0.5, 1.0 - vUserMask));
+    vec3 maskBase = mix(userMaskColor, angleMaskColor, effectiveMaskType);
+    vec3 litMask = maskBase * 0.55
+                 + maskBase * diff1 * vec3(1.00, 0.96, 0.88) * 0.55
+                 + maskBase * diff2 * vec3(0.80, 0.60, 0.50) * 0.15
+                 + vec3(spec);
+
+    // Blend: 100% mask colour at the boundary, fading to 0% at falloff distance
+    vec3 color = mix(litTeal, litMask, maskEffect);
 
     gl_FragColor = vec4(color, 1.0);
   }
@@ -371,6 +434,7 @@ export function updateMaterial(material, displacementTexture, settings) {
   u.symmetricDisplacement.value   = settings.symmetricDisplacement   ? 1 : 0;
   u.useDisplacement.value         = settings.useDisplacement         ? 1 : 0;
   u.textureAspect.value.set(settings.textureAspectU ?? 1, settings.textureAspectV ?? 1);
+  u.boundaryFalloffDist.value       = settings.boundaryFalloff           ?? 0.0;
 }
 
 // ── Internal ──────────────────────────────────────────────────────────────────
@@ -399,6 +463,10 @@ function buildUniforms(tex, settings) {
     symmetricDisplacement:    { value: settings.symmetricDisplacement   ? 1 : 0 },
     useDisplacement:          { value: settings.useDisplacement         ? 1 : 0 },
     textureAspect:            { value: new THREE.Vector2(settings.textureAspectU ?? 1, settings.textureAspectV ?? 1) },
+    boundaryEdgeTex:          { value: createFallbackDataTexture() },
+    boundaryEdgeCount:        { value: 0 },
+    boundaryEdgeTexWidth:     { value: 1.0 },
+    boundaryFalloffDist:        { value: settings.boundaryFalloff ?? 0.0 },
   };
 }
 
@@ -412,3 +480,12 @@ function createFallbackTexture() {
   t.wrapS = t.wrapT = THREE.RepeatWrapping;
   return t;
 }
+
+function createFallbackDataTexture() {
+  const data = new Float32Array(4);
+  const t = new THREE.DataTexture(data, 1, 1, THREE.RGBAFormat, THREE.FloatType);
+  t.minFilter = THREE.NearestFilter;
+  t.magFilter = THREE.NearestFilter;
+  t.needsUpdate = true;
+  return t;
+}