@lovelace_lol/loom3 1.0.31 → 1.0.33

package/README.md

@@ -1,10 +1,9 @@
 # Loom3
 
-_Author: Jonathan Sutton Fields._
 
 The missing character controller for Three.js! Loom3 allows you to bring humanoid and animal characters to life. Loom3 is based on the Facial Action Coding System (FACS) as the basis of its mappings, providing a morph and bone mapping library for controlling high-definition 3D characters in Three.js.
 
-Loom3 provides mappings that connect [Facial Action Coding System (FACS)](https://en.wikipedia.org/wiki/Facial_Action_Coding_System) Action Units to the morph targets and bone transforms found in Character Creator 4 (CC4) characters. Instead of manually figuring out which blend shapes correspond to which facial movements, you can simply say `setAU(12, 0.8)` and the library handles the rest.
+Loom3 provides mappings that connect [Facial Action Coding System (FACS)](https://en.wikipedia.org/wiki/Facial_Action_Coding_System) Action Units to the morph targets and bone transforms found in 3d character assets. Instead of manually figuring out which blend shapes correspond to which facial movements, you can simply say `setAU(12, 0.8)` and the library handles the rest.
 
 > **Note:** If you previously used the `loomlarge` npm package, it has been renamed to `@lovelace_lol/loom3`.
 
@@ -309,7 +308,7 @@ import { Loom3, CC4_PRESET } from '@lovelace_lol/loom3';
 const loom = new Loom3({ profile: CC4_PRESET });
 ```
 
-You can also resolve presets by name and apply overrides without cloning the full preset:
+You can also look up presets by name and extend them without cloning the full preset:
 
 ```typescript
 import { Loom3 } from '@lovelace_lol/loom3';
@@ -387,13 +386,13 @@ Use preset helpers when you want a stable entry point by model class instead of
 
 ```typescript
 import {
-  resolvePreset,
-  resolvePresetWithOverrides,
+  getPreset,
+  getPresetWithProfile,
 } from '@lovelace_lol/loom3';
 
-const preset = resolvePreset('cc4');
+const preset = getPreset('cc4');
 
-const resolved = resolvePresetWithOverrides('cc4', {
+const extended = getPresetWithProfile('cc4', {
   morphToMesh: { face: ['Object_9'] },
 });
 ```
@@ -567,10 +566,10 @@ import {
   analyzeModel,
   validateMappings,
   generateMappingCorrections,
-  resolvePreset,
+  getPreset,
 } from '@lovelace_lol/loom3';
 
-const preset = resolvePreset('cc4');
+const preset = getPreset('cc4');
 const modelData = extractModelData(model, meshes, animations);
 const gltfData = extractFromGLTF(gltf); // Same ModelData shape, one-step GLTF wrapper
 
@@ -674,12 +673,12 @@ Open in LoomLarge: [Properties tab](https://loomlarge.web.app/?drawer=open&tab=p
 
 ### Extending an existing preset
 
-Use `resolveProfile` to override specific mappings while keeping the rest:
+Use `extendPresetWithProfile` to override specific mappings while keeping the rest:
 
 ```typescript
-import { CC4_PRESET, resolveProfile } from '@lovelace_lol/loom3';
+import { CC4_PRESET, extendPresetWithProfile } from '@lovelace_lol/loom3';
 
-const MY_PRESET = resolveProfile(CC4_PRESET, {
+const MY_PRESET = extendPresetWithProfile(CC4_PRESET, {
 
   // Override AU12 (smile) with custom morph names
   auToMorphs: {
@@ -2118,8 +2117,8 @@ This is a compact reference for the public surface exported by `@lovelace_lol/lo
 
 ### Presets and profiles
 
-- Presets: `CC4_PRESET`, `BETTA_FISH_PRESET`, `resolvePreset()`, `resolvePresetWithOverrides()`.
-- Profile composition: `resolveProfile()`.
+- Presets: `CC4_PRESET`, `BETTA_FISH_PRESET`, `getPreset()`, `getPresetWithProfile()`.
+- Profile composition: `extendPresetWithProfile()`.
 - CC4 exports: `VISEME_KEYS`, `VISEME_JAW_AMOUNTS`, `CONTINUUM_PAIRS_MAP`, `CONTINUUM_LABELS`, `AU_INFO`, `COMPOSITE_ROTATIONS`, `AU_MIX_DEFAULTS`.
 - Compatibility helpers: `isMixedAU()`, `hasLeftRightMorphs()`.
 

package/dist/index.cjs

@@ -2900,7 +2900,7 @@ var HairPhysicsController = class {
   }
 };
 
-// src/mappings/resolveProfile.ts
+// src/mappings/extendPresetWithProfile.ts
 var isPlainObject = (value) => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
@@ -2992,31 +2992,33 @@ var mergeHairPhysicsConfig = (base, override) => {
   }
   return merged;
 };
-function resolveProfile(base, override) {
+function extendPresetWithProfile(base, extension) {
+  if (!extension) {
+    return base;
+  }
+  const disabledRegions = extension.disabledRegions ? [...extension.disabledRegions] : base.disabledRegions ? [...base.disabledRegions] : void 0;
   return {
     ...base,
-    ...override,
-    auToMorphs: mergeRecord(base.auToMorphs, override.auToMorphs),
-    auToBones: mergeRecord(base.auToBones, override.auToBones),
-    boneNodes: mergeRecord(base.boneNodes, override.boneNodes),
-    morphToMesh: mergeRecord(base.morphToMesh, override.morphToMesh),
-    auFacePartToMeshCategory: base.auFacePartToMeshCategory || override.auFacePartToMeshCategory ? mergeRecord(base.auFacePartToMeshCategory || {}, override.auFacePartToMeshCategory || {}) : void 0,
-    visemeKeys: override.visemeKeys ? [...override.visemeKeys] : [...base.visemeKeys],
-    visemeMeshCategory: override.visemeMeshCategory ?? base.visemeMeshCategory,
-    auMixDefaults: base.auMixDefaults || override.auMixDefaults ? mergeRecord(base.auMixDefaults || {}, override.auMixDefaults || {}) : void 0,
-    auInfo: base.auInfo || override.auInfo ? mergeRecord(base.auInfo || {}, override.auInfo || {}) : void 0,
-    eyeMeshNodes: override.eyeMeshNodes ?? base.eyeMeshNodes,
-    compositeRotations: override.compositeRotations ?? base.compositeRotations,
-    meshes: base.meshes || override.meshes ? mergeRecord(base.meshes || {}, override.meshes || {}) : void 0,
-    continuumPairs: base.continuumPairs || override.continuumPairs ? mergeRecord(base.continuumPairs || {}, override.continuumPairs || {}) : void 0,
-    continuumLabels: base.continuumLabels || override.continuumLabels ? mergeRecord(base.continuumLabels || {}, override.continuumLabels || {}) : void 0,
-    annotationRegions: mergeAnnotationRegions(base.annotationRegions, override.annotationRegions),
-    hairPhysics: mergeHairPhysicsConfig(base.hairPhysics, override.hairPhysics)
+    ...extension,
+    auToMorphs: mergeRecord(base.auToMorphs, extension.auToMorphs),
+    auToBones: mergeRecord(base.auToBones, extension.auToBones),
+    boneNodes: mergeRecord(base.boneNodes, extension.boneNodes),
+    morphToMesh: mergeRecord(base.morphToMesh, extension.morphToMesh),
+    auFacePartToMeshCategory: base.auFacePartToMeshCategory || extension.auFacePartToMeshCategory ? mergeRecord(base.auFacePartToMeshCategory || {}, extension.auFacePartToMeshCategory || {}) : void 0,
+    visemeKeys: extension.visemeKeys ? [...extension.visemeKeys] : [...base.visemeKeys],
+    visemeMeshCategory: extension.visemeMeshCategory ?? base.visemeMeshCategory,
+    auMixDefaults: base.auMixDefaults || extension.auMixDefaults ? mergeRecord(base.auMixDefaults || {}, extension.auMixDefaults || {}) : void 0,
+    auInfo: base.auInfo || extension.auInfo ? mergeRecord(base.auInfo || {}, extension.auInfo || {}) : void 0,
+    eyeMeshNodes: extension.eyeMeshNodes ?? base.eyeMeshNodes,
+    compositeRotations: extension.compositeRotations ?? base.compositeRotations,
+    meshes: base.meshes || extension.meshes ? mergeRecord(base.meshes || {}, extension.meshes || {}) : void 0,
+    continuumPairs: base.continuumPairs || extension.continuumPairs ? mergeRecord(base.continuumPairs || {}, extension.continuumPairs || {}) : void 0,
+    continuumLabels: base.continuumLabels || extension.continuumLabels ? mergeRecord(base.continuumLabels || {}, extension.continuumLabels || {}) : void 0,
+    annotationRegions: mergeAnnotationRegions(base.annotationRegions, extension.annotationRegions),
+    disabledRegions,
+    hairPhysics: mergeHairPhysicsConfig(base.hairPhysics, extension.hairPhysics)
   };
 }
-function applyProfileToPreset(base, override) {
-  return override ? resolveProfile(base, override) : base;
-}
 
 // src/presets/bettaFish.ts
 var BONES = [
@@ -3803,22 +3805,24 @@ var ANNOTATION_REGIONS = [
     name: "gills",
     bones: ["GILL_L", "GILL_R"],
     paddingFactor: 1.6,
-    children: ["throat", "gill"],
+    children: ["gill_left", "gill_right"],
     expandAnimation: "outward"
   },
   {
-    name: "throat",
+    name: "gill_left",
     bones: ["GILL_L", "GILL_L_MID", "GILL_L_TIP"],
     parent: "gills",
     paddingFactor: 1.4,
-    cameraAngle: 270
+    cameraAngle: 270,
+    style: { lineDirection: "left" }
   },
   {
-    name: "gill",
+    name: "gill_right",
     bones: ["GILL_R", "GILL_R_MID", "GILL_R_TIP"],
     parent: "gills",
     paddingFactor: 1.4,
-    cameraAngle: 90
+    cameraAngle: 90,
+    style: { lineDirection: "right" }
   }
 ];
 var BETTA_FISH_PROFILE = {
@@ -3855,7 +3859,7 @@ var AU_MAPPING_CONFIG = BETTA_FISH_PRESET;
 var FISH_AU_MAPPING_CONFIG = BETTA_FISH_PRESET;
 
 // src/presets/index.ts
-function resolvePreset(presetType) {
+function getPreset(presetType) {
   switch (presetType) {
     case "fish":
     case "skeletal":
@@ -3866,9 +3870,8 @@ function resolvePreset(presetType) {
       return CC4_PRESET;
   }
 }
-function resolvePresetWithOverrides(presetType, overrides) {
-  const base = resolvePreset(presetType);
-  return applyProfileToPreset(base, overrides);
+function getPresetWithProfile(presetType, profile) {
+  return extendPresetWithProfile(getPreset(presetType), profile);
 }
 
 // src/engines/three/Loom3.ts
@@ -3944,8 +3947,8 @@ var _Loom3 = class _Loom3 {
     __publicField(this, "isRunning", false);
     /** Store original emissive colors for highlight reset */
     __publicField(this, "originalEmissive", /* @__PURE__ */ new Map());
-    const basePreset = config.presetType ? resolvePreset(config.presetType) : CC4_PRESET;
-    this.config = applyProfileToPreset(basePreset, config.profile);
+    const basePreset = config.presetType ? getPreset(config.presetType) : CC4_PRESET;
+    this.config = extendPresetWithProfile(basePreset, config.profile);
     this.mixWeights = { ...this.config.auMixDefaults };
     this.animation = animation || new AnimationThree();
     this.compositeRotations = this.config.compositeRotations || COMPOSITE_ROTATIONS;
@@ -5354,7 +5357,30 @@ var BLENDING_MODES = {
   // THREE.NoBlending
 };
 
-// src/characters/resolveCharacterConfig.ts
+// src/regions/normalizeRegionTree.ts
+function normalizeDisabledNames(disabledNames) {
+  return new Set((disabledNames ?? []).filter((name) => Boolean(name)));
+}
+function normalizeRegionTree(regions, disabledNames) {
+  if (!regions) return void 0;
+  const disabled = normalizeDisabledNames(disabledNames);
+  const nextRegions = regions.filter((region) => !disabled.has(region.name)).map((region) => ({
+    ...region,
+    children: region.children ? [...region.children] : void 0
+  }));
+  const remainingNames = new Set(nextRegions.map((region) => region.name));
+  return nextRegions.map((region) => {
+    const nextChildren = region.children?.filter((child) => remainingNames.has(child));
+    const nextParent = region.parent && remainingNames.has(region.parent) ? region.parent : void 0;
+    return {
+      ...region,
+      parent: nextParent,
+      children: nextChildren && nextChildren.length > 0 ? nextChildren : void 0
+    };
+  });
+}
+
+// src/characters/extendCharacterConfigWithPreset.ts
 var PROFILE_OVERRIDE_KEYS = [
   "name",
   "animalType",
@@ -5382,6 +5408,7 @@ var PROFILE_OVERRIDE_KEYS = [
   "continuumPairs",
   "continuumLabels",
   "annotationRegions",
+  "disabledRegions",
   "hairPhysics"
 ];
 function isPlainObject2(value) {
@@ -5500,11 +5527,11 @@ function applyCharacterProfileToPreset(config) {
   if (!presetType) {
     return null;
   }
-  return applyProfileToPreset(resolvePreset(presetType), extractProfileOverrides(config));
+  return extendPresetWithProfile(getPreset(presetType), extractProfileOverrides(config));
 }
-function orderResolvedRegions(resolvedRegions, prioritizedLists) {
-  if (!resolvedRegions) return void 0;
-  const resolvedByName = new Map(resolvedRegions.map((region) => [region.name, region]));
+function orderExtendedRegions(extendedRegions, prioritizedLists) {
+  if (!extendedRegions) return void 0;
+  const extendedByName = new Map(extendedRegions.map((region) => [region.name, region]));
   const orderedNames = [];
   const seen = /* @__PURE__ */ new Set();
   for (const regions of prioritizedLists) {
@@ -5514,12 +5541,12 @@ function orderResolvedRegions(resolvedRegions, prioritizedLists) {
       orderedNames.push(region.name);
     }
   }
-  for (const region of resolvedRegions) {
+  for (const region of extendedRegions) {
     if (seen.has(region.name)) continue;
     seen.add(region.name);
     orderedNames.push(region.name);
   }
-  return orderedNames.map((name) => resolvedByName.get(name)).filter((region) => Boolean(region));
+  return orderedNames.map((name) => extendedByName.get(name)).filter((region) => Boolean(region));
 }
 function extendCharacterConfigWithPreset(config) {
   const presetType = config.auPresetType;
@@ -5527,25 +5554,26 @@ function extendCharacterConfigWithPreset(config) {
     return config;
   }
   const profileOverrides = extractProfileOverrides(config);
-  const presetResolvedProfile = applyCharacterProfileToPreset(config);
-  if (!presetResolvedProfile) {
+  const extendedPresetProfile = applyCharacterProfileToPreset(config);
+  if (!extendedPresetProfile) {
     return config;
   }
-  const presetRegions = presetResolvedProfile.annotationRegions;
+  const presetRegions = extendedPresetProfile.annotationRegions;
   const mergedRegions = mergeRegionsByName(presetRegions, config.regions);
-  const resolvedRegions = orderResolvedRegions(
+  const normalizedRegions = normalizeRegionTree(
     mergedRegions,
+    profileOverrides.disabledRegions
+  );
+  const extendedRegions = orderExtendedRegions(
+    normalizedRegions,
     [config.regions, profileOverrides.annotationRegions, presetRegions]
   );
   return {
     ...config,
-    ...presetResolvedProfile,
-    regions: resolvedRegions ?? config.regions
+    ...extendedPresetProfile,
+    regions: extendedRegions ?? config.regions
   };
 }
-function resolveCharacterConfig(config) {
-  return extendCharacterConfigWithPreset(config);
-}
 var DEFAULT_HEAD_BONE_NAMES = ["CC_Base_Head", "Head", "head", "Bip01_Head"];
 var DEFAULT_REFERENCE_HEIGHT = 1.8;
 var DEFAULT_FORWARD_OFFSET = 0.08;
@@ -6892,10 +6920,10 @@ exports.VISEME_JAW_AMOUNTS = VISEME_JAW_AMOUNTS;
 exports.VISEME_KEYS = VISEME_KEYS;
 exports.analyzeModel = analyzeModel;
 exports.applyCharacterProfileToPreset = applyCharacterProfileToPreset;
-exports.applyProfileToPreset = applyProfileToPreset;
 exports.collectMorphMeshes = collectMorphMeshes;
 exports.detectFacingDirection = detectFacingDirection;
 exports.extendCharacterConfigWithPreset = extendCharacterConfigWithPreset;
+exports.extendPresetWithProfile = extendPresetWithProfile;
 exports.extractFromGLTF = extractFromGLTF;
 exports.extractModelData = extractModelData;
 exports.extractProfileOverrides = extractProfileOverrides;
@@ -6903,17 +6931,15 @@ exports.findFaceCenter = findFaceCenter;
 exports.fuzzyNameMatch = fuzzyNameMatch;
 exports.generateMappingCorrections = generateMappingCorrections;
 exports.getModelForwardDirection = getModelForwardDirection;
+exports.getPreset = getPreset;
+exports.getPresetWithProfile = getPresetWithProfile;
 exports.hasLeftRightMorphs = hasLeftRightMorphs;
 exports.isMixedAU = isMixedAU;
 exports.isPresetCompatible = isPresetCompatible;
 exports.mergeCharacterRegionsByName = mergeRegionsByName;
 exports.resolveBoneName = resolveBoneName;
 exports.resolveBoneNames = resolveBoneNames;
-exports.resolveCharacterConfig = resolveCharacterConfig;
 exports.resolveFaceCenter = resolveFaceCenter;
-exports.resolvePreset = resolvePreset;
-exports.resolvePresetWithOverrides = resolvePresetWithOverrides;
-exports.resolveProfile = resolveProfile;
 exports.suggestBestPreset = suggestBestPreset;
 exports.validateMappingConfig = validateMappingConfig;
 exports.validateMappings = validateMappings;