cubing 0.35.18 → 0.36.0

package/dist/esm/puzzle-geometry/index.js

@@ -1,7 +1,7 @@
 import {
   Move,
   QuantumMove
-} from "../chunk-HVZKPYTG.js";
+} from "../chunk-CFNRQVBC.js";
 
 // src/cubing/puzzle-geometry/FaceNameSwizzler.ts
 var FaceNameSwizzler = class {
@@ -23,6 +23,8 @@ var FaceNameSwizzler = class {
   setGripNames(names) {
     this.gripnames = names;
   }
+  // split a string into face names and return a list of
+  // indices.
   splitByFaceNames(s) {
     const r = [];
     let at = 0;
@@ -45,6 +47,7 @@ var FaceNameSwizzler = class {
     }
     return r;
   }
+  // cons a grip from an array of numbers.
   joinByFaceIndices(list) {
     let sep = "";
     const r = [];
@@ -57,6 +60,34 @@ var FaceNameSwizzler = class {
     }
     return r.join("");
   }
+  /*
+   *   Try to match something the user gave us with some geometric
+   *   feature.  We used to have strict requirements:
+   *
+   *      a)  The set of face names are prefix free
+   *      b)  When specifying a corner, all coincident planes were
+   *          specified
+   *
+   *   But, to allow megaminx to have more reasonable and
+   *   conventional names, and to permit shorter canonical
+   *   names, we are relaxing these requirements and adding
+   *   new syntax.  Now:
+   *
+   *      a)  Face names need not be syntax free.
+   *      b)  When parsing a geometric name, we use greedy
+   *          matching, so the longest name that matches the
+   *          user string at the current position is the one
+   *          assumed to match.
+   *      c)  Underscores are permitted to separate face names
+   *          (both in user input and in geometric
+   *          descriptions).
+   *      d)  Default names of corner moves where corners have
+   *          more than three corners, need only include three
+   *          of the corners.
+   *
+   *   This code is not performance-sensitive so we can do it a
+   *   slow and simple way.
+   */
   spinmatch(userinput, longname) {
     if (userinput === longname) {
       return true;
@@ -89,6 +120,7 @@ var FaceNameSwizzler = class {
       return false;
     }
   }
+  /* same as above, but permit both to have v's on the end. */
   spinmatchv(userinput, longname) {
     if (userinput.endsWith("v") && longname.endsWith("v")) {
       return this.spinmatch(
@@ -141,6 +173,7 @@ var FTONotationMapper = class {
       return r;
     }
   }
+  // we never rewrite click moves to these moves.
   notationToExternal(move) {
     let fam = move.family;
     if (fam.length > 0 && fam[fam.length - 1] === "v") {
@@ -162,6 +195,7 @@ var FaceRenamingMapper = class {
     this.internalNames = internalNames;
     this.externalNames = externalNames;
   }
+  // TODO:  consider putting a cache in front of this
   convertString(grip, a, b) {
     let suffix = "";
     if ((grip.endsWith("v") || grip.endsWith("v")) && grip <= "_") {
@@ -233,6 +267,7 @@ var MegaminxScramblingNotationMapper = class {
     }
     return this.child.notationToInternal(move);
   }
+  // we never rewrite click moves to these moves.
   notationToExternal(move) {
     if (move.family === "DRRv" && Math.abs(move.amount) === 1) {
       return new Move(
@@ -313,6 +348,7 @@ var NxNxNCubeMapper = class {
     }
     return move;
   }
+  // do we want to map slice moves to E/M/S instead of 2U/etc.?
   notationToExternal(move) {
     const grip = move.family;
     if (!(move.innerLayer || move.outerLayer)) {
@@ -411,6 +447,7 @@ var PyraminxNotationMapper = class {
       return null;
     }
   }
+  // we never rewrite click moves to these moves.
   notationToExternal(move) {
     if (this.wcaHack && move.innerLayer === 2 && move.outerLayer === null) {
       for (const [external, internal] of Object.entries(pyraminxFamilyMapWCA)) {
@@ -499,6 +536,7 @@ var SkewbNotationMapper = class {
     }
     return null;
   }
+  // we never rewrite click moves to these moves.
   notationToExternal(move) {
     for (const [external, internal] of Object.entries(skewbFamilyMap)) {
       if (this.child.spinmatchv(move.family, internal)) {
@@ -581,25 +619,46 @@ function parseOptions(argv) {
   return { puzzleDescription, options };
 }
 var PuzzleGeometryFullOptions = class {
+  // scramble?
   constructor(options = {}) {
     this.verbosity = 0;
+    // verbosity (console.log)
     this.allMoves = false;
+    // generate outer block moves
     this.vertexMoves = false;
+    // generate vertex moves
     this.addRotations = false;
+    // add symmetry information to ksolve output
     this.moveList = null;
+    // move list to generate
     this.fixedOrientation = false;
+    // eliminate any orientations
     this.fixedPieceType = null;
+    // fix a piece?
     this.orientCenters = false;
+    // orient centers?
+    // TODO: Group these into a single object?
     this.includeCornerOrbits = true;
+    // include corner orbits
     this.includeCenterOrbits = true;
+    // include center orbits
     this.includeEdgeOrbits = true;
+    // include edge orbits
+    // Overrides the previous options.
     this.excludeOrbits = [];
+    // exclude these orbits
     this.optimizeOrbits = false;
+    // optimize PermOri
     this.grayCorners = false;
+    // make corner sets gray
     this.grayCenters = false;
+    // make center sets gray
     this.grayEdges = false;
+    // make edge sets gray
     this.puzzleOrientation = null;
+    // single puzzle orientation from options
     this.puzzleOrientations = null;
+    // puzzle orientation override object from options // TODO: is this needed?
     this.scrambleAmount = 0;
     Object.assign(this, options);
   }
@@ -656,6 +715,7 @@ function lcm(a, b) {
   return a / gcd(a, b) * b;
 }
 var Perm = class {
+  // The permutation itself
   constructor(a) {
     this.n = a.length;
     this.p = a;
@@ -845,6 +905,7 @@ var PGOrbitsDef = class {
     }
     return result;
   }
+  // TODO: return type.
   toKPuzzleDefinition(includemoves) {
     const orbits = {};
     const start = {};
@@ -993,9 +1054,13 @@ var PGOrbitsDef = class {
       this.forcenames
     );
   }
+  // replace the solved state with a new scrambled state.
   scramble(n) {
     this.solved = this.solved.mul(this.getScrambleTransformation(n));
   }
+  // generate a new "random" position based on an entropy pool
+  // this should be significantly faster and more random than just
+  // doing a large number of random moves, especially on big puzzles.
   getScrambleTransformation(n) {
     if (n < 100) {
       n = 100;
@@ -1081,6 +1146,7 @@ var _PGOrbit = class {
     }
     return true;
   }
+  // in-place mutator
   killOri() {
     const n = this.perm.length;
     for (let i = 0; i < n; i++) {
@@ -1103,6 +1169,7 @@ var _PGOrbit = class {
     }
     return new Perm(newPerm);
   }
+  // returns tuple of sets of identical pieces in this orbit
   identicalPieces() {
     const done = [];
     const n = this.perm.length;
@@ -1191,6 +1258,7 @@ var _PGOrbit = class {
       }
     }
   }
+  // TODO: return type
   toKPuzzle() {
     const n = this.perm.length;
     if (this.isIdentity()) {
@@ -1449,6 +1517,7 @@ var PGPuzzles = {
   pentultimate: "d f 0",
   "master pentultimate": "d f 0.1",
   "elite pentultimate": "d f 0 f 0.145905",
+  // exact value for starminx is sqrt(5(5-2 sqrt(5))/3)
   starminx: "d v 0.937962370425399",
   "starminx 2": "d f 0.23606797749979",
   "pyraminx crystal": "d f 0.447213595499989",
@@ -1568,6 +1637,9 @@ var Quat = class {
     t.a = this.a;
     return t;
   }
+  // return any vector orthogonal to the given one.  Find the smallest
+  // component (in absolute value) and return the cross product of that
+  // axis with the given vector.
   orthogonal() {
     const ab = Math.abs(this.b);
     const ac = Math.abs(this.c);
@@ -1580,6 +1652,8 @@ var Quat = class {
       return this.cross(new Quat(0, 0, 0, 1)).normalize();
     }
   }
+  // return the Quaternion that will rotate the this vector
+  // to the b vector through rotatepoint.
   pointrotation(b) {
     const a = this.normalize();
     b = b.normalize();
@@ -1596,6 +1670,8 @@ var Quat = class {
     r.a = a.dot(h);
     return r;
   }
+  // given two vectors, return the portion of the first that
+  // is not in the direction of the second.
   unproject(b) {
     return this.sum(b.smul(-this.dot(b) / (this.len() * b.len())));
   }
@@ -1636,6 +1712,11 @@ var Quat = class {
     }
     return 0;
   }
+  /**
+   * Cuts a face by this plane, or returns null if there
+   * is no intersection.
+   * @param face The face to cut.
+   */
   cutface(face) {
     const d = this.a;
     let seen = 0;
@@ -2050,17 +2131,21 @@ var copyright = "PuzzleGeometry 0.1 Copyright 2018 Tomas Rokicki.";
 var permissivieMoveParsing = false;
 function defaultnets() {
   return {
+    // four faces: tetrahedron
     4: [["F", "D", "L", "R"]],
+    // six faces: cube
     6: [
       ["F", "D", "L", "U", "R"],
       ["R", "F", "", "B", ""]
     ],
+    // eight faces: octahedron
     8: [
       ["F", "D", "L", "R"],
       ["D", "F", "BR", ""],
       ["BR", "D", "", "BB"],
       ["BB", "BR", "U", "BL"]
     ],
+    // twelve faces:  dodecahedron; U/F/R/F/BL/BR from megaminx
     12: [
       ["U", "FF", "", "", "", ""],
       ["FF", "U", "R", "FR", "FL", "L"],
@@ -2068,6 +2153,7 @@ function defaultnets() {
       ["DR", "R", "", "BB", "", ""],
       ["BB", "DR", "BR", "BL", "DL", "DD"]
     ],
+    // twenty faces: icosahedron
     20: [
       ["R", "C", "F", "E"],
       ["F", "R", "L", "U"],
@@ -2084,6 +2170,7 @@ function defaultnets() {
 }
 function defaultcolors() {
   return {
+    // the colors should use the same naming convention as the nets, above.
     4: {
       F: "#44ee00" /* Green */,
       D: "#ffff00" /* Yellow */,
@@ -2322,22 +2409,27 @@ function defaultOrientations() {
       ["FLR", [0, 1, 0]],
       ["F", [0, 0, 1]]
     ],
+    // FLR towards viewer
     6: [
       ["U", [0, 1, 0]],
       ["F", [0, 0, 1]]
     ],
+    // URF towards viewer
     8: [
       ["U", [0, 1, 0]],
       ["F", [0, 0, 1]]
     ],
+    // FLUR towards viewer
     12: [
       ["U", [0, 1, 0]],
       ["FF", [0, 0, 1]]
     ],
+    // F towards viewer
     20: [
       ["GUQMJ", [0, 1, 0]],
       ["F", [0, 0, 1]]
     ]
+    // F towards viewer
   };
 }
 function findelement(a, p) {
@@ -2459,10 +2551,15 @@ function toFaceCoords(q, maxdist) {
 var PuzzleGeometry = class {
   constructor(puzzleDescription, options) {
     this.puzzleDescription = puzzleDescription;
+    // cubies in each cubie set
     this.cmovesbyslice = [];
+    // parsed move list
     this.duplicatedFaces = [];
+    // which faces are duplicated
     this.duplicatedCubies = [];
+    // which cubies are duplicated
     this.fixedCubie = -1;
+    // fixed cubie, if any
     this.net = [];
     this.colors = [];
     this.notationMapper = new NullMapper();
@@ -2955,6 +3052,8 @@ var PuzzleGeometry = class {
     }
     return s;
   }
+  // same as above, but instead of returning an encoded string, return
+  // an array with offsets.
   keyface3(face) {
     const cm = face.centermass();
     const r = [];
@@ -3377,6 +3476,8 @@ var PuzzleGeometry = class {
     }
     return newmv.modified({ family: this.swizzler.unswizzle(newmv.family) });
   }
+  // We use an extremely permissive parse here; any character but
+  // digits are allowed in a family name.
   stringToBlockMove(mv) {
     const re = RegExp("^(([0-9]+)-)?([0-9]+)?([^0-9]+)([0-9]+'?)?$");
     const p = mv.match(re);
@@ -3898,6 +3999,7 @@ var PuzzleGeometry = class {
     }
     return false;
   }
+  // TODO: This is only public for testing; can we make it private again?
   getOrbitsDef(fortwisty, includemoves = true) {
     const setmoves = [];
     if (fortwisty) {
@@ -4163,6 +4265,10 @@ var PuzzleGeometry = class {
     }
     return new Perm(r);
   }
+  // Given a rotation description that says to align feature1
+  // with a given vector, and then as much as possible feature2
+  // with another given vector, return a Quaternion that
+  // performs this rotation.
   getOrientationRotation(desiredRotation) {
     const [feature1name, [x1, y1, z1]] = desiredRotation[0];
     const direction1 = new Quat(0, x1, -y1, z1);
@@ -4423,6 +4529,10 @@ ${svg.join(
     )}</svg>`;
     return html;
   }
+  // The colorfrac parameter says how much of the face should be
+  // colored (vs dividing lines); we default to 0.77 which seems
+  // to work pretty well.  It should be a number between probably
+  // 0.4 and 0.9.
   get3d(options) {
     const stickers = [];
     const rot = this.getInitial3DRotation();
@@ -4516,6 +4626,11 @@ ${svg.join(
       textureMapper: { getuv: g }
     };
   }
+  //  From the name of a geometric element (face, vertex, edge), get a
+  //  normal vector respecting the default orientation.  This is useful
+  //  to define the initial position of the camera in a 3D scene.  The
+  //  return value is normalized, so multiply it by the camera distance.
+  //  Returns undefined if no such geometric element.
   getGeoNormal(geoname) {
     const rot = this.getInitial3DRotation();
     const grip = this.swizzler.unswizzle(geoname);