kanji-recognizer 0.1.1 → 0.2.0

package/README.md

@@ -7,8 +7,9 @@ A lightweight, dependency-free JavaScript library for Kanji stroke order recogni
 
 ## ✨ Features
 
-- **🎯 Accurate Recognition** - Uses geometric resampling algorithm to compare user strokes against KanjiVG data
-- **📝 Stroke-by-Stroke Validation** - Enforces correct stroke order for proper kanji learning
+- **🎯 Accurate Recognition** - Uses geometric resampling algorithm with centroid-based alignment for robust recognition
+- **📝 Multiple Modes** - Supports Stroke-by-Stroke validation, Full Kanji check, and Free Write
+- **🖼️ Image Export** - Export your drawings as PNG images for AI analysis or saving
 - **🎨 Fully Customizable** - Easy to style colors, animations, and recognition sensitivity
 - **⚡ Lightweight** - Zero dependencies, pure SVG-based rendering
 - **📱 Mobile-Friendly** - Touch-optimized with pointer events
@@ -87,6 +88,7 @@ const writer = new KanjiWriter(elementId, kanjiData, options);
   // Behavior
   showGhost: true,               // Show red guide for next stroke
   showGrid: true,                // Show background grid
+  checkMode: 'stroke',           // 'stroke' (immediate), 'full' (manual), or 'free' (no validation)
   
   // Recognition (Adjustable!)
   passThreshold: 15,             // Lower = stricter (10-20 recommended)
@@ -141,6 +143,25 @@ Clean up resources and remove event listeners.
 writer.destroy();
 ```
 
+##### `exportImage(options)`
+Export the current drawing as a base64 PNG image.
+
+```javascript
+const dataUrl = await writer.exportImage({
+  includeGrid: false,
+  backgroundColor: '#ffffff'
+});
+// Send dataUrl to AI or save it
+```
+
+##### `check()`
+Manually trigger evaluation of all collected strokes (only for `checkMode: 'full'`).
+
+```javascript
+const result = writer.check();
+if (result.success) console.log("All strokes correct!");
+```
+
 #### Event Callbacks
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kanji-recognizer",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "A robust Kanji stroke order recognition and validation library using KanjiVG data.",
     "main": "src/index.js",
     "type": "module",
@@ -41,4 +41,4 @@
         "url": "https://github.com/mxggle/kanji-recognizer/issues"
     },
     "homepage": "https://github.com/mxggle/kanji-recognizer#readme"
-}
+}

package/src/GeometryUtil.js

@@ -57,32 +57,73 @@ export class GeometryUtil {
         return newPoints;
     }
 
+    /**
+     * Get the centroid (center of mass) of a set of points
+     */
+    static getCentroid(points) {
+        if (!points || points.length === 0) return { x: 0, y: 0 };
+        let sumX = 0;
+        let sumY = 0;
+        for (const p of points) {
+            sumX += p.x;
+            sumY += p.y;
+        }
+        return { x: sumX / points.length, y: sumY / points.length };
+    }
+
     /**
      * Compare two strokes. Returns a score (lower is better, 0 is perfect).
-     * Checks shape and direction.
+     * Now includes translation normalization to be more robust.
      * @param {Array} userPoints - User's drawn points
      * @param {Array} targetPoints - Target stroke points
-     * @param {number} startDistThreshold - Maximum allowed start point distance (default: 40)
+     * @param {Object} options - Thresholds and weights
      */
-    static compareStrokes(userPoints, targetPoints, startDistThreshold = 40) {
+    static compareStrokes(userPoints, targetPoints, options = {}) {
+        const {
+            startDistThreshold = 50,
+            translationWeight = 0.3, // How much absolute position matters (0-1)
+            shapeWeight = 0.7        // How much shape accuracy matters (0-1)
+        } = options;
+
         const resampledUser = this.resample(userPoints);
         const resampledTarget = this.resample(targetPoints);
 
-        // 1. Direction Check: Check if start and end points match roughly
+        // 1. Initial Position Check
+        // We still want the stroke to start *somewhere* near the expected start
         const startDist = this.distance(resampledUser[0], resampledTarget[0]);
-        const endDist = this.distance(resampledUser[resampledUser.length - 1], resampledTarget[resampledTarget.length - 1]);
+        if (startDist > startDistThreshold) return Infinity;
+
+        // 2. Alignment (Translation Normalization)
+        // Calculate centroids
+        const userCentroid = this.getCentroid(resampledUser);
+        const targetCentroid = this.getCentroid(resampledTarget);
+
+        // Calculate translation cost (distance between centroids)
+        const translationCost = this.distance(userCentroid, targetCentroid);
 
-        // If start is far from start, it's definitely wrong (or drawn backwards)
-        // We penalize this heavily.
-        if (startDist > startDistThreshold) return Infinity; // Way off
+        // 3. Shape Check (Aligned average distance)
+        let shapeDist = 0;
+        const dx = targetCentroid.x - userCentroid.x;
+        const dy = targetCentroid.y - userCentroid.y;
 
-        // 2. Shape Check: Average distance between points
-        let totalDist = 0;
         for (let i = 0; i < resampledUser.length; i++) {
-            totalDist += this.distance(resampledUser[i], resampledTarget[i]);
+            // Compare user point (shifted to target space) vs target point
+            const shiftedUserPoint = {
+                x: resampledUser[i].x + dx,
+                y: resampledUser[i].y + dy
+            };
+            shapeDist += this.distance(shiftedUserPoint, resampledTarget[i]);
         }
-        const avgDist = totalDist / resampledUser.length;
+        const shapeCost = shapeDist / resampledUser.length;
+
+        // 4. Combined weighted score
+        // This is more robust because if you draw the right shape slightly shifted,
+        // the shapeCost will be low, and translationCost will be moderate,
+        // allowing it to pass even if the absolute coordinates are off.
+        const totalScore = (shapeCost * shapeWeight) + (translationCost * translationWeight);
+
+        console.log(`Recognition Debug - Shape: ${shapeCost.toFixed(2)}, Trans: ${translationCost.toFixed(2)}, Total: ${totalScore.toFixed(2)}`);
 
-        return avgDist;
+        return totalScore;
     }
 }

package/src/KanjiVGParser.js

@@ -40,7 +40,7 @@ export class KanjiVGParser {
             throw new Error('Invalid character: must be a non-empty string');
         }
 
-        let code = char.charCodeAt(0).toString(16);
+        let code = char.codePointAt(0).toString(16).toLowerCase();
         while (code.length < 5) code = "0" + code;
         return code;
     }
@@ -55,8 +55,8 @@ export class KanjiVGParser {
         }
 
         let hex = char;
-        // If it looks like a single character, convert to hex
-        if (char.length === 1 && char.charCodeAt(0) > 255) {
+        // If it looks like a single character (including surrogate pairs), convert to hex
+        if (Array.from(char).length === 1) {
             hex = this.getHex(char);
         }
 

package/src/KanjiWriter.js

@@ -18,17 +18,12 @@ export class KanjiWriter {
             // Toggles
             showGhost: true,              // Show red guide for next stroke
             showGrid: true,               // Show the background grid
+            checkMode: 'stroke',          // 'stroke' (immediate), 'full' (manual), or 'free' (no validation)
 
             // Appearance
             strokeWidth: 4,
             gridWidth: 0.5,
             ghostOpacity: "0.1",
-
-            // Animations
-            stepDuration: 500,
-            hintDuration: 800,
-            snapDuration: 200,
-
             ...options
         };
 
@@ -44,6 +39,7 @@ export class KanjiWriter {
         this.currentStrokeIndex = 0;
         this.isDrawing = false;
         this.currentPoints = [];
+        this.userStrokes = []; // Store strokes for 'full' mode
 
         // Use options.width/height in initSVG
         this.width = this.options.width;
@@ -112,7 +108,7 @@ export class KanjiWriter {
         // Optional: render faint outline of the next stroke
         this.bgGroup.innerHTML = '';
 
-        if (!this.options.showGhost) return;
+        if (!this.options.showGhost || this.options.checkMode === 'free') return;
 
         // If we want to show the full ghost:
         this.kanjiData.forEach((d, i) => {
@@ -136,7 +132,8 @@ export class KanjiWriter {
     attachEvents() {
         // Store bound functions as instance properties for cleanup
         this.boundStart = (e) => {
-            if (this.currentStrokeIndex >= this.kanjiData.length) return; // Finished
+            // Only stop drawing if in a validation mode and kanji is finished
+            if (this.options.checkMode !== 'free' && this.currentStrokeIndex >= this.kanjiData.length) return;
             e.preventDefault();
             this.isDrawing = true;
             this.currentPoints = [];
@@ -168,7 +165,24 @@ export class KanjiWriter {
         this.boundEnd = (e) => {
             if (!this.isDrawing) return;
             this.isDrawing = false;
-            this.evaluateStroke();
+
+            if (this.options.checkMode === 'stroke') {
+                this.evaluateStroke();
+            } else if (this.options.checkMode === 'full') {
+                // In 'full' mode, we just store the points and keep the path
+                this.userStrokes.push({
+                    points: this.currentPoints,
+                    path: this.currentPath
+                });
+                this.currentStrokeIndex++;
+                this.renderUpcomingStrokes();
+            } else {
+                // In 'free' mode, we just leave the path in the currentGroup
+                // and maybe track it if we want to support undo later
+                this.userStrokes.push({
+                    path: this.currentPath
+                });
+            }
         };
 
         this.svg.addEventListener('pointerdown', this.boundStart);
@@ -258,11 +272,64 @@ export class KanjiWriter {
         setTimeout(() => { pathRef.remove(); }, 600);
     }
 
+    /**
+     * Manual check for 'full' mode
+     * @returns {Object} result - Success and detailed results per stroke
+     */
+    check() {
+        if (this.options.checkMode !== 'full') {
+            console.warn("check() called but checkMode is not 'full'");
+            return;
+        }
+
+        const results = [];
+        let allCorrect = true;
+
+        // Evaluate each user stroke against corresponding target stroke
+        for (let i = 0; i < this.kanjiData.length; i++) {
+            const userStroke = this.userStrokes[i];
+            const targetD = this.kanjiData[i];
+
+            if (!userStroke) {
+                results.push({ success: false, message: "Missing stroke" });
+                allCorrect = false;
+                continue;
+            }
+
+            const result = this.recognizer.evaluate(userStroke.points, targetD);
+            results.push(result);
+
+            if (!result.success) {
+                allCorrect = false;
+                userStroke.path.setAttribute("stroke", this.options.incorrectColor);
+            } else {
+                userStroke.path.setAttribute("stroke", this.options.correctColor);
+            }
+        }
+
+        // If there are extra strokes, they are incorrect
+        if (this.userStrokes.length > this.kanjiData.length) {
+            allCorrect = false;
+            for (let i = this.kanjiData.length; i < this.userStrokes.length; i++) {
+                this.userStrokes[i].path.setAttribute("stroke", this.options.incorrectColor);
+                results.push({ success: false, message: "Extra stroke" });
+            }
+        }
+
+        if (allCorrect && this.userStrokes.length === this.kanjiData.length) {
+            console.log("Full Kanji Correct!");
+            if (this.onComplete) this.onComplete();
+        }
+
+        return { success: allCorrect, results };
+    }
+
     /**
      * Public API: Clear the canvas and reset progress
      */
     clear() {
         this.currentStrokeIndex = 0;
+        this.userStrokes = [];
         this.drawnGroup.innerHTML = '';
         this.currentGroup.innerHTML = '';
         this.bgGroup.innerHTML = '';
@@ -389,4 +456,62 @@ export class KanjiWriter {
             }
         });
     }
+
+    /**
+     * Export the current drawing as a base64 PNG image
+     * @param {Object} options - Export options (includeGrid, includeGhost, etc.)
+     * @returns {Promise<string>} Base64 Data URL
+     */
+    async exportImage(options = {}) {
+        const {
+            includeGrid = false,
+            includeGhost = false,
+            backgroundColor = "#ffffff",
+            width = 109,
+            height = 109
+        } = options;
+
+        // Create a clone of the SVG to manipulate without affecting UI
+        const clone = this.svg.cloneNode(true);
+
+        // Find the groups in the clone
+        const groups = Array.from(clone.querySelectorAll('g'));
+        const gridGroup = groups[0];
+        const bgGroup = groups[1];
+
+        // Toggle visibility based on options
+        if (!includeGrid && gridGroup) gridGroup.setAttribute('visibility', 'hidden');
+        if (!includeGhost && bgGroup) bgGroup.setAttribute('visibility', 'hidden');
+
+        // Ensure background color if SVG doesn't have one
+        clone.style.background = backgroundColor;
+
+        // Serialize to XML
+        const serializer = new XMLSerializer();
+        const svgString = serializer.serializeToString(clone);
+        const svgBlob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });
+        const url = URL.createObjectURL(svgBlob);
+
+        return new Promise((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => {
+                const canvas = document.createElement('canvas');
+                // Use higher resolution for export if desired, but 109x109 is KanjiVG base
+                // We scales up to the container's current pixel size for better quality
+                const scale = 2; // Export at 2x for better AI recognition
+                canvas.width = width * scale;
+                canvas.height = height * scale;
+
+                const ctx = canvas.getContext('2d');
+                ctx.fillStyle = backgroundColor;
+                ctx.fillRect(0, 0, canvas.width, canvas.height);
+                ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+
+                URL.revokeObjectURL(url);
+                resolve(canvas.toDataURL('image/png'));
+            };
+            img.onerror = reject;
+            img.src = url;
+        });
+    }
 }

package/src/StrokeRecognizer.js

@@ -68,7 +68,11 @@ export class StrokeRecognizer {
             return { success: false, score: 100, message: "Length mismatch" };
         }
 
-        const score = GeometryUtil.compareStrokes(userPoints, targetPoints, this.options.startDistThreshold);
+        const score = GeometryUtil.compareStrokes(userPoints, targetPoints, {
+            startDistThreshold: this.options.startDistThreshold,
+            translationWeight: 0.3,
+            shapeWeight: 0.7
+        });
 
         return {
             success: score < this.options.passThreshold,